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improved  use  of  technology  by  U.S.  industry. 
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This  report  is  a programmer's  manual  for  a microcomputer  package  which 
was  designed  by  the  National  Institute  of  Standards  and  Technology  to  assist 
the  Internal  Revenue  Service  in  choosing  locations  for  its  posts-of-duty 
which  will  minimize  costs  to  the  IRS  and  to  the  taxpayer.  The  package  was 
written  in  two  sections  of  code,  one  in  FORTRAN  and  the  other  in  PASCAL. 

This  manual  describes  the  FORTRAN  driver  which  handles  graphics  displays  and 
controls  input  and  output  for  the  solution  procedure. 
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Section  I:  Introduction 


This  paper  is  one  of  a series  of  reports  documenting  the  Internal 
Revenue  Service  Post-of-Duty  Location  Modeling  System,  which  was  developed 
for  the  IRS  Research  Division  by  the  Center  for  Computing  and  Applied 
Mathematics  of  the  National  Institute  of  Standards  and  Technology.  The 
reports  in  the  series  are  as  follows. 


1)  The  Internal  Revenue  Service  Post-of-Duty  Location  Modeling  System: 

Final  Report 

This  report  describes  the  post-of-duty  location  problem  and  its 
mathematical  model.  It  discusses  the  types  of  data  which  are  considered 
in  calculating  costs,  describes  the  methods  used  to  solve  the  location 
problem,  and  gives  a brief  introduction  to  the  computer  implementation  of 
the  model.  (NIST  Contact:  Paul  D.  Domich) 


2)  The  Internal  Revenue  Service  Post-of-Dutv  Location  Modeling  System: 
User ' s Manual 

This  report  is  a user's  guide  for  the  post-of-duty  location  computer 
system.  It  gives  hardware  and  software  requirements,  instructions  for 
installing  the  system,  descriptions  of  data  files,  and  detailed 
instructions  for  operating  the  system.  (NIST  Contact:  Marjorie  A. 
McClain) 


3)  The  Internal  Revenue  Service  Post-of-Dutv  Location  Modeling  System: 
Programmer's  Manual  for  FORTRAN  Driver 

The  post-of-duty  location  program  is  written  in  two  sections  of  code,  one 
in  FORTRAN  and  the  other  in  PASCAL.  This  report  describes  the  FORTRAN 
driver  which  handles  graphics  displays  and  controls  input  and  output  for 
the  solution  procedure.  The  report  includes  an  alphabetical  list  of  the 
FORTRAN  routines,  describing  the  purpose,  the  calling  sequence  and  the 
variables  of  each  routine.  (NIST  Contact:  Marjorie  A.  McClain) 


4)  The  Internal  Revenue  Service  Post-of-Dutv  Location  Modeling  System: 
Programmer's  Manual  for  PASCAL  Solver 

This  report  describes  the  second  part  of  the  post-of-duty  location 
program,  the  PASCAL  solver.  It  discusses  the  algorithms  and  data 
structures  used  to  solve  a location  problem.  (NIST  Contact:  Paul  D. 
Domich) 

It  is  assumed  that  the  reader  of  this  programmer's  manual  is  thoroughly 
familiar  with  IBM-PC  DOS,  with  the  FORTRAN  language,  and  with  the  POD 
location  system  user's  manual. 
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Section  II:  Software  Requirements 


The  following  software  is  required  to  be  able  to  use  and  make  changes 
to  the  POD  location  system  programs. 

1)  IBM-PC  DOS  (Version  2.1  or  later) 

2)  IBM  Professional  FORTRAN  (Version  1.19) 

3)  Turbo  PASCAL  (Version  5.0) 

4)  IBM  Graphical  Kernel  System  (Version  1.00) 

(GKS  includes  the  Virtual  Device  Interface  and  device  drivers.  See 
the  user's  manual  for  information  on  how  to  set  up  the  device 
drivers  in  the  AUTOEXEC.BAT  and  CONFIG.SYS  files.) 

5)  Source  code  for  the  POD  location  system,  contained  in  the  following 
files . 

Geographic  Data  Initialization  Programs  -- 
GDTINST1 . FOR 
GDTINST2 . FOR 

System  Driver  Programs  -- 
LOCATE . BAT 
DRIVER. FOR 
GKSUTIL. FOR 
IOSUBS . FOR 
MAPSUBS . FOR 
MENUSUBS . FOR 

System  Solver  Programs  -- 
SOLVER. PAS 
DSTRUCT . PAS 
FIVCLR. PAS 
GREEDY. PAS 
INIT.PAS 
INTCHG . PAS 
LGRN . PAS 
PODCLR . PAS 

6)  Executable  code  for  the  POD  location  system,  contained  in  the 
following  files. 

Geographic  Data  Initialization  Programs  -- 
GDTINST1.EXE 
GDTINST2.EXE 

System  Driver  Programs  -- 
LOCATE . BAT 
DRIVER . EXE 

System  Solver  Program  -- 
SOLVER . EXE 

Only  a subset  of  this  software  is  required  for  a user  who  just  wants  to  run 
the  system  and  not  make  any  changes  to  it.  See  the  user's  manual  for  user 
software  requirements  and  also  for  general  hardware  requirements. 

Note:  Reference  to  a tradename  or  product  in  this  report  does  not  imply 
endorsement  by  the  National  Institute  of  Standards  and  Technology. 


2 


Section  III:  Overview  of  FORTRAN  Routines 


The  POD  location  system  requires  the  use  of  geographic  data  files 
obtained  from  Geographic  Data  Technology,  Inc.  (GDT) . This  data  must  be 
processed  before  it  is  distributed  to  the  end  user,  in  order  to  convert  it 
to  a useable  format.  The  files  GDTINST1.F0R  and  GDTINST2.F0R  contain  the 
source  code  for  processing  the  GDT  data.  The  use  of  these  programs  is 
described  more  completely  in  "Instructions  for  Preparing  the  IRS  Post-of- 
Duty  Location  System  for  Distribution  to  District  Offices". 

The  POD  location  system  itself  is  written  in  two  separate  sections  of 
code.  One  section  is  written  in  FORTRAN  and  contains  the  code  for  drawing 
maps  and  initializing  location  problems.  It  allows  the  user  to  display 
workload,  set  up  a location  problem,  display  a map  of  the  solution,  and 
create  a report  file.  The  second  section  is  written  in  PASCAL  and  contains 
the  code  for  solving  a location  problem.  Data  is  passed  between  the  two 
sections  of  code  using  files. 

A batch  file  called  LOCATE.BAT  controls  the  flow  of  execution  between 
the  two  sections  of  code.  LOCATE.BAT  first  checks  to  see  if  files  called 
ERRORS. GKS  and  EXITFILE.BAT  exist  from  a previous  run.  If  so,  it  erases 
them.  Then  LOCATE.BAT  enters  a loop  which  passes  control  between  the 
FORTRAN  section  (stored  in  DRIVER.EXE)  and  the  PASCAL  section  (stored  in 
SOLVER.EXE).  DRIVER  is  always  entered  first.  Then,  depending  on  actions 
taken  by  the  user,  either  SOLVER  is  entered  or  an  exit  is  taken  from  the 
loop.  In  the  first  case,  after  SOLVER  has  completed,  control  returns  to 
DRIVER  and  the  loop  repeats.  In  the  second  case,  a file  called  EXITFILE.BAT 
is  created  by  DRIVER.  It  contains  instructions  for  deleting  work  files 
created  during  the  run  and  for  printing  the  report  file.  This  new  batch 
file  is  executed,  and  then  LOCATE.BAT  terminates. 

The  FORTRAN  source  code  is  contained  in  five  files:  DRIVER. FOR, 

GKSUTIL. FOR,  IOSUBS.FOR,  MAPSUBS . FOR  and  MENUSUBS . FOR . DRIVER. FOR  contains 
the  main  program  DRIVER  along  with  most  of  the  high-level  subroutines.  The 
other  files  contain  various  lower-level  subroutines.  A complete  description 
of  each  subroutine  is  given  in  Section  IV. 

If  a change  is  made  in  a subroutine,  it  must  be  recompiled  by  typing 
"PROFORT  filename",  where  "filename"  is  the  name  of  the  source  code  file 
containing  the  changed  routine.  Then  the  program  must  be  relinked  by  typing 
"LINK  DRIVER  GKSUTIL  IOSUBS  MAPSUBS  MENUSUBS  \GKS\PFGKS , , NUL, 
\PROFORT\PROFORT  \GKS\GKS  \GKS\PFGKS  /S : 5000  /X:350".  (This  assumes  that 
the  POD  location  system  source  files  are  stored  in  the  current  directory, 
Professional  FORTRAN  files  are  in  a directory  called  \PR0F0RT,  and  GKS  files 
are  in  a directory  called  \GKS . These  path  names  may  be  changed.)  The 
result  is  a new  executable  file  called  DRIVER.EXE. 

The  PASCAL  solver  routines  are  described  in  "The  Internal  Revenue 
Service  Post-of-Duty  Location  Modeling  System:  Programmer's  Manual  for 
PASCAL  Solver". 
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Section  IV:  Description  of  Individual  FORTRAN  Routines 


This  section  contains  a brief  description  of  each  of  the  FORTRAN 
routines.  Information  is  provided  on  the  purpose  of  the  routine,  the  name 
of  the  file  containing  its  source  code,  names  of  input  and  output  variables, 
and  names  of  programs  called  by  the  routine  and  programs  which  call  it.  The 
routines  are  listed  in  alphabetical  order. 


SUBROUTINE  ADJ (IERR , ID .MAXIND .NINDEX , INDEX.MAXZPS , PNTR) : 

This  subroutine  reads  the  GDT  zip  code  boundary  file  (in  DIME  format)  and 
creates  a binary  direct-access  adjacency  file  ADJACENT. id.  For  each  zip 
code  that  appears  in  both  the  centroid  file  and  the  workload  file,  two 
records  are  created  in  the  adjacency  file.  The  first  record  contains  the 
index  of  the  zip  code,  the  number  of  adjacent  zip  codes,  and  the  zip  code 
number.  The  second  record  contains  a list  of  the  adjacent  zip  code  indices. 


Note:  This  routine  should  be  compiled  with  the  Profort  /B  option  because  of 
the  large  size  of  the  index  array. 


Source  Code  Location  -- 
GDTINST2 .FOR 


Input  Variables  -- 

ID:  CHARACTER*2 

Two-digit  district  identification  number 
MAXIND:  INTEGERS 

Maximum  allowed  number  of  elements  in  INDEX  array 
MAXZPS : INTEGERS 

Maximum  allowed  number  of  elements  in  PNTR  array 


Output  Variables  -- 
IERR:  INTEGER*4 

Error  flag  -- 
IERR=0  for  normal  return 
IERR=1  if  an  error  was  encountered 
NINDEX:  INTEGERS 


Number  of  elements  in  index  array 
INDEX(NINDEX) : INTEGERS 

Array  of  zip  code  index  numbers  -- 
INDEX(I)=JO0  means  that  zip  code  MINZIP+I-1 
appears  in  both  the  centroid  file  and  the 
workload  file  and  is  assigned  index  number  J 
PNTR(MAXZPS) : INTEGERS 

Array  of  pointers  from  index  numbers  to  positions 
of  zip  codes  in  centroid  file 


Programs  Called  -- 
COMP 

Calling  Programs  -- 
GDTINST2 
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SUBROUTINE  BEEP: 
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This  subroutine  beeps  the  speaker. 
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Source  Code  Location  -- 
GKSUTIL. FOR 

Programs  Called  -- 
None 

Calling  Programs  -- 

STEMAP 

ZIPMAP 

SUBROUTINE  BORDER (XMIN , XMAX , YMIN , YMAX) : 

This  subroutine  draws  a border  around  the  current  screen  window.  The 
provided  window  limits  are  slightly  reduced  before  the  border  is  drawn; 
otherwise  some  sides  of  the  border  may  not  appear  because  of  roundoff  error 
in  the  conversion  from  world  coordinates  to  screen  coordinates.  (See  the 
GKS  manual  for  definitions  of  graphics  terms.) 

Source  Code  Location  -- 
GKSUTIL. FOR 

Input  Variables  -- 
XMIN:  REAL*4 

Smallest  x value  of  world  coordinates 
XMAX:  REAL* 4 

Largest  x value  of  world  coordinates 
YMIN:  REAL*4 

Smallest  y value  of  world  coordinates 
YMAX : REAL*4 

Largest  y value  of  world  coordinates 

Programs  Called  -- 

BOX 

GSPLCI 

Calling  Programs  -- 

ERSMNU 

MAPKEY 

MENU 20 

MENU21 

MENU 2 2 

MENU 2 3 

SPLTWN 

TOPMNU 

ZIPMAP 


SUBROUTINE  BOX (XMIN, XMAX, YMIN, YMAX) : 

This  subroutine  draws  a box.  (See  the  GKS  manual  for  definitions  of 
graphics  terms.) 


Source  Code  Location  -- 
GKSUTIL. FOR 

Input  Variables 
XMIN : REAL* 4 

X-coordinate  of  lower  left  corner  (in  world  coordinates) 
XMAX:  REAL* 4 

X-coordinate  of  upper  right  corner  (in  world  coordinates) 
YMIN:  REAL*4 

Y-coordinate  of  lower  left  corner  (in  world  coordinates) 
YMAX:  REAL*4 

Y-coordinate  of  upper  right  corner  (in  world  coordinates) 

Programs  Called  -- 
GPL 

Calling  Programs  -- 

BORDER 

MENU20 

MENU 21 

SUBROUTINE  CENSRT(IERR, ID, MAXM , M , XCENT , YCENT, INDEX, PNT, ZIP5) : 

This  subroutine  reads  the  centroid  file  CENTROID. id  and  calls  a heapsort 
program  to  sort  the  centroids  according  to  increasing  x and  y coordinates 
(This  is  done  to  speed  up  the  process  of  searching  for  zip  codes  on  a map 
It  also  speeds  up  the  drawing  of  maps.)  Arrays  are  set  up  to  store  the 
following  information  from  the  file:  centroids,  pointers  to  the  zip  code 

boundary  file,  zip  code  index  numbers,  and  five-digit  zip  code  numbers. 
This  subroutine  is  executed  whenever  the  program  DRIVER  is  entered. 

Source  Code  Location  -- 
DRIVER. FOR 

Input  Variables  -- 
ID:  CHARACTER*2 

District  number 
MAXM:  INTEGER*4 

Maximum  number  of  zip  codes  allowed 

Output  Variables  -- 


I ERR: 

INTEGER*4 

Error  flag  - - 

IERR=0  for  normal  return 

IERR=1  if  an  error  was  encountered 

M: 

INTEGER*4 

Number  of  zip  codes. 

XCENT (M) : 

REAL*4 

Array  containing  x-coordinates 

of  centroids, 

sorted  according  to  increasing 

x and  y 

YCENT (M) : 

REAL* 4 

Array  containing  y-coordinates 

of  centroids, 

sorted  according  to  increasing 

x and  y 

INDEX(M) : 

INTEGER*2 
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Zip  code  index  array  -- 

INDEX(I)  is  the  original  index  of  the  zip  code  with 
centroid  (XCENT(I) , YCENT(I) ) before  sorting 
PNT(M)  : INTEGERS 

Pointer  array  -- 

PNT(I)  points  to  the  beginning  of  information  on  the 
zip  code  with  centroid  (XCENT(I) ,YCENT(I) ) in  the  zip 
code  boundary  file 
ZIP5  (M) : INTEGERS 

Array  of  five-digit  zip  codes,  in  original  sequential  order 

Programs  Called  -- 

PAUSE 

SORT 

Calling  Programs  -- 
DRIVER 


SUBROUTINE  CENTRD(IERR, ID, NZIPS , ZIP5 , PNTR.NCENT) : 

This  subroutine  reads  the  GDT  zip  code  inventory  file  and  creates  a binary 
direct-access  centroid  file  CENTROID. id.  Zip  codes  with  zero  area  (point 
zips)  are  not  included  in  the  centroid  file.  A pointer  is  included  with 
each  centroid  which  points  to  the  corresponding  zip  code  in  the  zip  code 
boundary  file  ZIPCODE.id.  A post  office  name  file  PONAMES.id  is  also 
created,  listing  each  zip  code  and  its  name. 

Source  Code  Location  -- 
GDTINST1 . FOR 


Input  Variables  -- 

ID:  CHARACTER*2 

Two-digit  district  identification  number 
NZIPS : INTEGERS 

Number  of  distinct  zip  codes  in  the  zip  code 
boundary  file 
ZIP5 (NZIPS ) : INTEGERS 

Array  of  five-digit  zip  code  numbers,  in  sequential 
order 


PNTR(NZIPS):  INTEGER*^ 

Pointer  into  boundary  file  -- 

PNTR(I)  is  the  record  number  of  the  beginning  of 
information  on  zip  code  ZIP5(I)  in  the  boundary  file 


Output  Variable  -- 
I ERR:  I NT EGER* 4 

Error  flag  -- 
IERR=0  for  normal  return 
IERR=1  if  an  error  was  encountered 
NCENT : INTEGER*4 

Number  of  distinct  zip  codes  which  appear  in  both  the 
inventory  file  and  the  boundary  file 

Programs  Called  -- 
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None 


Calling  Programs  -- 
GDTINST1 

SUBROUTINE  CHOICE (WKID , CHDNR) : 

This  subroutine  initializes  choice  mode  (function  keys) . To  use  the 
function  keys,  call  GRQCH  ("Request  Choice").  (See  the  GKS  manual  for 
definitions  of  graphics  terms.) 

Source  Code  Location  -- 
GKSUTIL. FOR 

Input  Variable  -- 
WKID:  INTEGER*2 

Workstation  identifier 

Output  Variable  -- 
CHDNR:  INTEGER*2 

Choice  device  number 

Programs  Called  -- 
GSCHM 

Calling  Programs  -- 

DISPLY 

DRIVER 

SUBROUTINE  CLSGKS (WKID) : 

This  subroutine  closes  GKS  and  resets  the  screen  mode  for  text.  (This 
requires  the  presence  of  ANSI. SYS  in  the  CONFIG.SYS  file.  See  the  GKS 
manual  for  definitions  of  graphics  terms.) 

Source  Code  Location  -- 
GKSUTIL. FOR 

Input  Variable  -- 
WKID:  INTEGER*2 

Workstation  identifier 

Programs  Called  -- 

GCLKS 

GCLWK 

GDAWK 

Calling  Programs  -- 

DISPLY 

DRIVER 

MAPKEY 

STEMAP 

STYLE 

ZIPMAP 
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SUBROUTINE  COMP  ( I ERR , ID , MINZIP , MAXIND , NINDEX , INDEX , 

MAXZPS ,PNTR) : 

This  subroutine  compares  zip  codes  in  the  centroid  file  with  zip  codes  in 
the  workload  file.  It  assigns  an  index  number  to  each  zip  code  which 
appears  in  both  files.  It  also  creates  a file  COMPARE. id  listing  zip  codes 
which  appear  in  only  one  of  the  files. 

Source  Code  Location  -- 
GDTINST2 . FOR 

Input  Variables  -- 

ID:  CHARACTER*2 

Two-digit  district  identification  number 
MAXIND:  INTEGERS 

Maximum  allowed  number  of  elements  in  INDEX  array 
MAXZPS : INTEGERS 

Maximum  allowed  number  of  elements  in  PNTR  array 


Output  Variables  -- 
I ERR:  INTEGERS 

Error  flag  -- 
IERR=0  for  normal  return 
IERR=1  if  an  error  was  encountered 
MINZIP:  I NT EGER* 4 

Minimum  zip  code  in  centroid  file 
NINDEX:  INTEGER*4 


Number  of  elements  in  INDEX  array 
INDEX(NINDEX) : INTEGER*4 

Array  of  zip  code  index  numbers  -- 
INDEX(I)=JoO  means  that  zip  code  MINZIP+I-1 
appears  in  both  the  centroid  file  and  the 
workload  file  and  is  assigned  index  number  J 
PNTR(MAXZPS) : INTEGER*4 

Array  of  pointers  from  index  numbers  to  positions 
of  zip  codes  in  centroid  file 


Programs  Called  -- 
None 

Calling  Programs  -- 
ADJ 

SUBROUTINE  CONVRT (INPUT, OUTPUT ) : 

This  subroutine  converts  a one-  or  two-digit  integer  into  a two-character 
string  (used  for  printing  out  the  date  and  time). 

Source  Code  Location  -- 
IOSUBS .FOR 

Input  Variable  -- 
INPUT:  INTEGER*2 

Integer  between  0 and  99 
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Output  Variable  -- 
OUTPUT:  CHARACTER*2 

Two-character  string  version  of  input  integer 

Programs  Called  -- 
None 

Calling  Programs  -- 
REPFIL 

FUNCTION  COSTFN  (NCLASS  , SWITCH , WRK , IRSWT , IRSFCT , TXPWT , TXPFCT , 

MILjCST  , TRVDIF , DIST , SQFCST , SQFT)  : 

This  function  calculates  the  cost  of  assigning  a zip  code  to  a POD  site. 

The  cost  is  made  up  of  travel  costs  and  office  space  costs.  Travel  costs 
are  based  on  the  Individual  Master  File  (IMF)  and  Business  Master  File  (BMF) 
workload  generated  by  the  zip  code,  its  distance  from  the  POD  site,  and  the 
cost  per  mile.  However,  the  cost  may  be  weighted  by  several  user-supplied 
factors.  Office  space  costs  are  based  on  the  amount  of  space  required  to 
handle  the  workload  and  the  rental  cost  per  square  foot  for  office  space  at 
the  POD  site.  For  further  information  on  how  costs  are  computed,  see  "The 
Internal  Revenue  Service  Post-of-Duty  Location  Modeling  System:  Final 
Report" . 


Source  Code  Location  -- 
DRIVER. FOR 


Input  Variables 
NCLASS: 

SWITCH (NCLASS) : 

WRK(NCLASS) : 
IRSWT: 

IRSFCT (NCLASS ) : 
TXPWT: 

TXPFCT (NCLASS) : 
MILCST : 

TRVDIF: 

DIST: 


INTEGER*4 

Number  of  workload  columns  in  workload  file 
(not  including  display  columns) 

INTEGERS 

Array  indicating  which  columns  of  the  workload 
file  are  to  be  included  in  the  cost  calculation 
INTEGERS 

Workload  array  for  current  zip  code 
REAL*4 

Weight  (nonnegative  real  number)  to  be  assigned  to 
IRS  travel  costs 
REAL* 4 

Array  of  IRS  trip  factors 
REAL*4 

Weight  (nonnegative  real  number)  to  be  assigned  to 

taxpayer  travel  costs 

REAL*4 

Array  of  taxpayer  trip  factors 
REAL* 4 

Mileage  cost  ($/mile) 

REAL*4 

Travel  difficulty  factor  for  trips  between  current 

zip  code  and  current  POD  site 

REAL*4 

Distance  between  current  zip  code  and  current  POD 
site  (miles) 
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SQFCST : REAL*4 

Office  space  cost  for  current  POD  site 
($/square  foot/year) 

SQFT : REAL*4 

Office  space  factor  to  be  multiplied  by  total 
TDI ' s and  TDA's  (square  feet) 

Output  Variable  -- 
COSTFN : REAL* 8 

Cost  of  assigning  current  zip  code  to  current  POD 
site  ($) 

Programs  Called  -- 
None 

Calling  Programs  -- 
SOLVE 


SUBROUTINE  CRSBOX (WKID , TRN , STAT , XMIN , XMAX , YMIN , YMAX) : 

This  subroutine  creates  a cursor  box.  To  use  the  cursor,  first  move  the 
crosshair  cursor  to  one  corner  of  the  desired  box  and  enter  this  point. 

Then  a rectangular  cursor  will  appear  which  can  be  used  to  enter  the 
opposite  corner  of  the  box.  (See  the  GKS  manual  for  definitions  of  graphics 
terms . ) 


Source  Code  Location  -- 
GKSUTIL. FOR 

Input  Variables  -- 
WKID:  INTEGER*2 

Workstation  identifier 
TRN:  INTEGER*2 

Transformation  number 

Output  Variables  -- 
STAT:  INTEGER*2 

Cursor  status  indicator 
STAT=0 : Error  reading  cursor  locations 
STAT=1:  No  errors  encountered 
XMIN:  REAL*4 

X coordinate  of  lower  left  corner  of  box 
XMAX:  REAL*4 

X coordinate  of  upper  right  corner  of  box 
YMIN:  REAL*4 

Y coordinate  of  lower  left  corner  of  box 
YMAX : REAL*4 

Y coordinate  of  upper  right  corner  of  box 

Programs  Called  -- 

GINLC 

GPREC 

GQNT 

GRQLC 
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Calling  Programs  -- 
ZOOMIN 

SUBROUTINE  CURSOR (UKID.TRN, IPX, IPY) : 

This  subroutine  initializes  a cursor.  To  use  the  cursor,  call  GRQLC 
("Request  Locator").  (See  the  GKS  manual  for  definitions  of  graphics 
terms . ) 


Source  Code  Location  -- 
GKSUTIL. FOR 

Input  Variables  -- 
WKID:  INTEGERS 

Workstation  identifier 
TRN:  INTEGERS 

Transformation  number 
IPX:  REAL*4 

Initial  x position  of  cursor  in  world  coordinates 
IPY:  REALS 

Initial  y position  of  cursor  in  world  coordinates 

Programs  Called  -- 

GINLC 

GPREC 

Calling  Programs  -- 
MAPKEY 


SUBROUTINE  DI SPLY (IERR , ID , PALETT , NCLRS  , MENU , COLOR , MODIFY , 

M , XCENT , YCENT , INDEX , PNT , ZIPCLR , ZIP5 , 

MAXPLT , XPLOT , YPLOT , LONG , PERM)  : 

This  subroutine  is  the  driver  for  the  map-drawing  routines.  It  uses  GKS  to 
display  a state  map  and  then  allows  the  user  to  zoom  in  or  modify  the  colors 
on  the  map . 

Source  Code  Location  -- 
MAPSUBS . FOR 


Input  Variables 
ID: 

PALETT : 

NCLRS: 


MENU: 


CHARACTERS 
District  number 
INTEGERS 

Palette  identifier  (1  or  2) 
INTEGERS 

Number  of  colors  in  menu 
(only  used  if  MOD I FY= . TRUE . ) 
INTEGERS 

Menu  type  switch  (for  coloring)  -- 
MENU=0  for  general  coloring  menu 
MENU=1  for  menu  of  POD  types 
MENU=2  for  title  of  solution  map 
MENU=3  for  key  to  workload  map 
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COLOR: 

LOGICAL 

Color  indicator  -- 

COLOR=.TRUE.  if  an  array  of  zip  code  colors  is 
provided 

COLOR= . FALSE . otherwise 

MODIFY: 

LOGICAL 

Color  modification  indicator  -- 

MODIFY= . TRUE . if  the  array  of  zip  code  colors  is 
allowed  to  be  modified 
MODIFY” . FALSE . otherwise 

M: 

INTEGER*4 

XCENT(M) : 

Number  of  zip  codes 
REAL* 4 

YCENT(M) : 

Array  containing  x-coordinates  of  centroids, 
sorted  according  to  increasing  x and  y 
REAL*4 

INDEX(M) : 

Array  containing  y-coordinates  of  centroids, 
sorted  according  to  increasing  x and  y 
INTEGER*2 

PNT(M) : 

Zip  code  index  array  -- 

INDEX(I)  is  the  original  index  of  the  zip  code 
with  centroid  (XCENT(I) , YCENT(I) ) before  sorting 
INTEGER*2 

ZIPCLR(M) : 

Pointer  array  -- 

PNT(I)  points  to  the  beginning  of  information  on 
the  zip  code  with  centroid  (XCENT(I) ,YCENT(I) ) in 
the  zip  code  boundary  file 
INTEGER*2 

Zip  code  color  array  -- 

ABS(ZIPCLR(INDEX(I) ) ) is  the  color  (a  number  from 
1 to  9)  of  the  zip  code  with  centroid  (XCENT(I), 
YCENT(I) ) 

(only  input  if  COLOR” . TRUE . ) 

Positive  value:  Centroid  drawn  as  asterisk 

ZIP5 (M) : 

Negative  value:  Centroid  drawn  as  small  box 
INTEGER*4 

Array  of  five-digit  zip  codes,  in  original 
sequential  order 

MAXPLT : 

INTEGER*4 

Maximum  number  of  plotting  points  allowed  in  a 
map  region 

Output  Variables  -- 


I ERR : 

INTEGER*4 

Error  flag  -- 

IERR=0  for  normal  return 

IERR=1  if  an  error  was  encountered 

COLOR : 

LOGICAL 

ZIPCLR(M) : 

Set  to  .TRUE,  if  color  array  was  created 
INTEGER*2 

Modified  zip  code  color  array 
(same  as  input  if  MODIFY” . FALSE . ) 

XPLOT ( 2 *MAXPLT ) : 

REAL*4 

Work  array  containing  x coordinates  of  points  to 
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plot  in  a map  region 
YPL0T(2*MAXPLT) : REAL*4 

Work  array  containing  y coordinates  of  points  to 
plot  in  a map  region 
LONG ( 2*MAXPLT) : REAL*4 

Work  array 

PERM(2*MAXPLT) : INTEGER*2 

Work  array 

Programs  Called  -- 

CHOICE 

CLSGKS 

GCLRWK 

GRQCH 

GSELNT 

GSTXCI 

GTX 

MAPKEY 

MARKZP 

MENU11 

MENU12 

OPNGKS 

STEMAP 

ZIPMAP 

ZOOMIN 

Calling  Programs  -- 

PODMAP 

SOLMAP 

WRKMAP 


PROGRAM  DRIVER: 


This  program  is  the  driver  for  the  IRS  post-of-duty  location  system.  It 
first  writes  a title  page  on  the  screen,  initializes  the  report  file,  and 
sets  up  data  structures  for  storing  zip  code  information.  Then  it  uses  GKS 
to  write  the  top-level  menu  on  the  screen  and  allows  the  user  to  choose 
which  phase  of  a location  problem  to  work  on.  The  possible  choices  are: 

(1)  Exit. 

(2)  Display  workload. 

(3)  Display  or  modify  initial  POD  sites. 

(4)  Solve  for  optimal  POD  locations. 

(5)  Display  optimal  POD  locations. 

(6)  Report  zip  code  and  staff  assignments. 


The  driver  terminates  in  one  of  two  possible  ways: 

(1)  The  user  chooses  "FI  - Exit"  from  the  top  menu.  In  this  case,  a 
file  called  EXITFILE.BAT  is  created  which  signals  the  batch 
program  LOCATE.BAT  to  leave  the  POD  location  system. 

(2)  The  user  chooses  "F4  - Solve  for  optimal  POD  locations"  from  the 
top  menu.  In  this  case,  LOCATE.BAT  passes  control  to  the 
solution  procedure  SOLVER.EXE.  When  the  solution  program  is 
finished,  control  returns  to  DRIVER.EXE. 
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The  following  data  files  must  exist  to  run  the  package  (the  "id"  extension 
should  be  replaced  by  the  district  identification  number) : 

(1)  OUTLINE. id:  State  outline  file 

(2)  ZIPCODE.id:  Zip  code  boundary  file 

(3)  CENTROID. id:  Zip  code  centroid  file 

(4)  PODSITE.id:  POD  site  and  fixed  cost  file 

(5)  WORKLOAD. id:  Workload  file 

(See  the  user's  manual  for  information  on  the  format  of  these  files.) 

The  following  common  block  is  required  by  the  graphics  package  GKS : 

COMMON  /GRACOM/  SIZE , INTARY 

SIZE  is  an  I NT EGER* 4 variable  set  equal  to  9000,  and  INTARY  is  an  INTEGER*4 
array  of  length  9000. 

Source  Code  Location  -- 
DRIVER. FOR 

Programs  Called  -- 

CENSRT 

CHOICE 

CLSGKS 

EXIT 

GRQCH 

HEADER 

OPNGKS 

PODMAP 

REPFIL 

REPSOL 

SOLMAP 

SOLVE 

TOPMNU 

WRKMAP 

SUBROUTINE  ERSMNU : 

This  subroutine  erases  a menu  from  the  left  window  of  the  screen. 

Source  Code  Location  -- 
MENUSUBS . FOR 

Programs  Called  -- 

BORDER 

GFA 

GQCNTN 

GSELNT 

STYLE 

Calling  Programs  -- 

MAPKEY 

ZOOM IN 

SUBROUTINE  EXIT ( ID) : 
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This  subroutine  is  executed  when  the  user  chooses  "FI  - Exit"  from  the  top 
menu.  It  creates  a batch  file  called  EXITFILE.BAT  which  contains 
instructions  for  deleting  work  files  created  by  the  rest  of  the  program.  It 
also  saves  modifications  to  the  PODSITE.id  file  and  sends  the  report  file  to 
the  line  printer  if  the  user  requests  it.  After  this  subroutine  has  been 
completed,  control  returns  to  the  batch  file  LOCATE.BAT,  which  checks  to  see 
if  EXITFILE.BAT  exists,  executes  it,  and  leaves  the  system. 

Source  Code  Location  - - 
DRIVER. FOR 

Input  Variable  -- 
ID:  CHARACTER*2 

District  number 

Programs  Called  -- 
None 

Calling  Programs  -- 
DRIVER 

SUBROUTINE  GACWK(WKID)  : 

GKS  routine  --  "ACTIVATE  WORKSTATION" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 
OPNGKS 

FUNCTION  GCDIST(LATl,lJONGl,LAT2,UONG2): 

This  function  calculates  the  great  circle  distance  (in  miles)  between  two 
points  on  the  earth,  given  the  latitude  and  longitude  of  each  point.  The 
formula  was  provided  by  Rand  McNally. 

Source  Code  Location  -- 
DRIVER. FOR 

Input  Variables  -- 
LAT1 : REAL*4 

Latitude  of  first  point 
L0NG1 : REAL* 4 

Longitude  of  first  point 
LAT2 : REAL*4 

Latitude  of  second  point 
LONG 2 : REAL*4 

Longitude  of  second  point 

Output  Variable  -- 
GCDIST : REAL* 4 

Distance  (in  miles)  between  first  and  second  points 

Programs  Called  -- 
None 
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Calling  Programs  -- 

SOLVE 

SPLTWN 

SUBROUTINE  GCLKS: 

GKS  routine  --  "CLOSE  KERNEL  SYSTEM" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 
CLSGKS 

SUBROUTINE  GCLRWK(VKID, COFL) : 

GKS  routine  --  "CLEAR  WORKSTATION" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 

DISPLY 

SPLTWN 

ZOOMIN 

SUBROUTINE  GCLWK(WKID) : 

GKS  routine  --  "CLOSE  WORKSTATION" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 
CLSGKS 

SUBROUTINE  GDAWK(WKID) : 

GKS  routine  --  "DEACTIVATE  WORKSTATION" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 
CLSGKS 

PROGRAM  GDTINSTl : 

This  program  converts  Geographic  Data  Technology  (GDT)  map  data  into  a 
format  to  be  used  by  the  IRS  POD  location  system.  Following  the  use  of  this 
program,  GDTINST2  should  be  run  to  complete  the  installation.  This  program 
should  be  used  only  by  the  person  preparing  the  data  files  for  distribution, 
not  by  the  end  user  of  the  system. 

Source  Code  Location  -- 
GDTINSTl. FOR 

Programs  Called  -- 

CENTRD 

OUTLIN 

ZIPBND 
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PROCRAM  CDTINST2: 


This  program  creates  a zip  code  adjacency  file  using  GDT's  DIME  format 
boundary  file.  It  also  compares  zip  codes  in  the  IRS  workload  file  with  zip 
codes  in  the  centroid  file  (created  by  GDTINST1) , and  creates  a file  listing 
any  mismatches.  This  program  should  be  used  only  by  the  person  preparing 
the  data  files  for  distribution,  not  by  the  end  user  of  the  system. 

Note:  This  program  should  be  compiled  with  the  Profort  /B  option. 

Source  Code  Location  -- 
GDTINST2 . FOR 

Programs  Called  -- 
ADJ 

SUBROUTINE  GEOFAC(DIFZIP,DIFPOD,DIFFAC,Kl,NREC,ID) : 

This  subroutine  allows  the  user  to  enter  factors  indicating  the  degree  of 
difficulty  of  travel  between  a zip  code  and  a POD  site.  The  values  are 
stored  in  the  file  DIFFACT.id. 

Source  Code  Location  -- 
IOSUBS . FOR 

Input  Variables  -- 

K1 : INTEGERS 

Maximum  number  of  non-unit  travel  difficulty  factors 
ID:  CHARACTERS 

District  number 


Output  Variables  -- 
DIFZIP(NREC) : INTEGERS 


five-digit  zip  code  array  for  use  with  travel 
difficulty  factors 
DIFPOD(NREC) : INTEGERS 

POD  zip  code  array  for  use  with  travel  difficulty 
factors 

DIFFAC (NREC) : REALS 

Array  of  travel  difficulty  factors  -- 
DIFFAC(I)  is  the  factor  associated  with  zip  code 
DIFZIP(I)  and  POD  site  DIFPOD(I) 

NREC:  INTEGERS 

Number  of  non-unit  travel  difficulty  factors 

Programs  Called  -- 
READBF 


Calling  Programs  -- 
SOLVE 

SUBROUTINE  GETDAT ( I YEAR , IMONTH , IDAY) : 

Professional  FORTRAN  routine  --  "GET  DATE" 
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(See  Professional  FORTRAN  manual  for  further  information.) 

Calling  Programs  -- 
REPFIL 

SUBROUTINE  GETTIM  ( IHOUR , IMINUTE , I SECOND , IHUNDRED  SECOND)  : 

Professional  FORTRAN  routine  --  "GET  TIME" 

(See  Professional  FORTRAN  manual  for  further  information.) 

Calling  Programs  -- 
REPFIL 

SUBROUTINE  GFA(N, PX, PY) : 

GKS  routine  --  "FILL  AREA" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 

ERSMNU 

MAPKEY 

MENU 20 

MENU21 

MENU 2 2 

MENU23 

ZIPMAP 

SUBROUTINE  GINKS  (NTYPES  , VNAMES  .WTYPES  .VERNUM)  : 

GKS  routine  --  "INITIALIZE  GKS" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 
OPNGKS 

SUBROUTINE  GINLC (WKID , LCDNR , TNR , I PX , I PY , PET , XMIN , XMAX , YMIN , YMAX , 
LDR.DATREC) : 

GKS  routine  --  "INITIALIZE  LOCATOR" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 

CRSBOX 

CURSOR 

SUBROUTINE  GINST (WKID , STDNR , ISTR , PET , XMIN , XMAX , YMIN , YMAX , BUFLEN , 
INI POS, LDR.DATREC) : 

GKS  routine  --  "INITIALIZE  STRING" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 

MARKZP 

ZOOM IN 
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SUBROUTINE  GOPKS (ERRFIL, SIZE) : 


GKS  routine  --  "OPEN  KERNEL  SYSTEM" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 
OPNGKS 

SUBROUTINE  GOPVK(VKID, CONID.WTYPE) : 

GKS  routine  --  "OPEN  WORKSTATION" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 
OPNGKS 

SUBROUTINE  GPL(N,PX,PY) : 

GKS  routine  --  "POLYLINE" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 
BOX 

MAPKEY 
MENU 11 
MENU12 
MENU20 
MENU21 
MENU22 
MENU23 
STEMAP 
TOPMNU 
ZIPMAP 

SUBROUTINE  GPM(N,PX,PY) : 

GKS  routine  --  "POLYMARKER" 

(See  GKS  manual  for  further  information.) 


Calling  Programs  -- 

MAPKEY 

MARKZP 

STEMAP 

ZIPMAP 

SUBROUTINE  GPREC  ( IL , IA , RL , RA , SL , MSTR , STR , MLDR , ERRIN , LDR , DATREC ) 

GKS  routine  --  "PACK  DATA  RECORD" 

(See  GKS  manual  for  further  information.) 


Calling  Programs  -- 

CRSBOX 

CURSOR 
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SUBROUTINE  GQCF(WTYPE , ERRIND , NCOLI , COLA , NPCI ) : 

GKS  routine  --  "INQUIRE  COLOR  FACILITIES" 

(See  GKS  manual  for  further  information.) 


Calling  Programs  -- 

MARKZP 

SETCOL 

STEMAP 

STYLE 

TOPMNU 

ZIPMAP 

ZOOM IN 

SUBROUTINE  GQCNTN  ( ERRIND , CTNR)  : 

GKS  routine  --  "INQUIRE  CURRENT  NORMALIZATION  TRANSFORMATION  NUMBER" 

(See  GKS  manual  for  further  information.) 


Calling  Programs  -- 

ERSMNU 

MARKZP 

MENU 11 

MENU 12 

MENU 20 

MENU 21 

MENU22 

MENU 2 3 

SUBROUTINE  GQMDS (WTYPE , ERRIND , DCUNIT , RX , RY , LX , LY) : 

GKS  routine  --  "INQUIRE  MAXIMUM  DISPLAY  SURFACE  SIZE" 

(See  GKS  manual  for  further  information.) 


Calling  Programs  -- 

MARKZP 

SPLTWN 

WINDOW 

ZOOM IN 

SUBROUTINE  GQNT(TNR, ERRIND .WINDOW , VI EWPT) : 

GKS  routine  --  "INQUIRE  NORMALIZATION  TRANSFORMATION" 
(See  GKS  manual  for  further  information.) 


Calling  Programs  -- 

CRSBOX 

MAPKEY 

MARKZP 

SUBROUTINE  GQTXX (WKI D , PX , PY , STR , ERRIND , CPX , CPY , TXEXPX , TXEXFY) : 

GKS  routine  --  "INQUIRE  TEXT  EXTENT" 

(See  GKS  manual  for  further  information.) 
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Calling  Programs  -- 

SPLTWN 

ZIPMAP 

SUBROUTINE  GRQCH(WKID , CHDNR, STAT.CHNR) : 

GKS  routine  --  "REQUEST  CHOICE" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 

DISPLY 

DRIVER 

MAPKEY 

SUBROUTINE  GRQLC(WKID,LCDNR,STAT,TNRtPX,PY) : 

GKS  routine  --  "REQUEST  LOCATOR" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 

CRSBOX 

MAPKEY 

SUBROUTINE  GRQST (WKID , STDNR , STAT , LOSTR , STR) : 

GKS  routine  --  "REQUEST  STRING" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 

MARKZP 

ZOOMIN 

SUBROUTINE  GSCHM(WKID , CHDNR , MODE , ESW) : 

GKS  routine  --  "SET  CHOICE  MODE" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 
CHOICE 

SUBROUTINE  GSCR(WKID , Cl , CR, CG , CB) : 

GKS  routine  --  "SET  COLOR  REPRESENTATION" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 
SETCOL 

SUBROUTINE  GSELNT(TNR) : 

GKS  routine  --  "SELECT  NORMALIZATION  TRANSFORMATION" 
(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 
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DISPLY 
ERSMNU 
MAPKEY 
MARKZP 
MENU 11 
MENU 12 
MENU 20 
MENU 21 
MENU 2 2 
MENU 2 3 
SPLTWN 
WINDOW 
ZOOMIN 

SUBROUTINE  GSFACI (COLI) : 

GKS  routine  --  "SET  FILL  AREA  COLOR  INDEX" 

(See  GKS  manual  for  further  information.) 


Calling  Programs  -- 
STYLE 

SUBROUTINE  GSFAIS (INTS) : 

GKS  routine  --  "SET  FILL  AREA  INTERIOR  STYLE" 
(See  GKS  manual  for  further  information.) 


Calling  Programs  -- 
STYLE 

SUBROUTINE  GSFASI(STYLI) : 

GKS  routine  --  "SET  FILL  AREA  STYLE  INDEX" 
(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 
STYLE 

SUBROUTINE  GSMK(MTYPE) : 

GKS  routine  --  "SET  POLYMARKER  TYPE" 

(See  GKS  manual  for  further  information.) 


Calling  Programs  -- 

MAPKEY 

MARKZP 

STEMAP 

ZIPMAP 

SUBROUTINE  GSPLCI (COLI) : 

GKS  routine  --  "SET  POLYLINE  COLOR  INDEX" 
(See  GKS  manual  for  further  information.) 
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Calling  Programs  -- 

BORDER 

MAPKEY 

MENU11 

MENU12 

MENU20 

MENU 21 

MENU 2 2 

MENU23 

STEMAP 

TOPMNU 

ZIPMAP 

SUBROUTINE  GSPMCI (COLI) : 

GKS  routine  --  "SET  POLYMARKER  COLOR  INDEX" 

(See  GKS  manual  for  further  information.) 


Calling  Programs  -- 

MAPKEY 

MARKZP 

MATCH 

STEMAP 

ZIPMAP 

SUBROUTINE  GSSTM(WKID , STDNR , MODE , ESV) : 

GKS  routine  --  "SET  STRING  MODE" 

(See  GKS  manual  for  further  information.) 


Calling  Programs  -- 
MARKZP 

SUBROUTINE  GSTXCI (COLI) : 

GKS  routine  --  "SET  TEXT  COLOR  INDEX" 

(See  GKS  manual  for  further  information.) 


Calling  Programs  -- 

DISPLY 

MAPKEY 

MARKZP 

MENU11 

MENU 12 

MENU 20 

MENU21 

MENU 2 2 

MENU23 

TOPMNU 

ZIPMAP 

ZOOMIN 

SUBROUTINE  GSVP(TNR ,XMIN ,XMAX, YMIN, YMAX) : 
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GKS  routine  --  "SET  VIEWPORT" 

(See  GKS  manual  for  further  information.) 

Calling  Programs  -- 

SPLTWN 

WINDOW 

SUBROUTINE  GSWKVP (WKID , XMIN , XMAX , YMIN , YMAX) : 

GKS  routine  --  "SET  WORKSTATION  VIEWPORT" 
(See  GKS  manual  for  further  information.) 


Calling  Programs  -- 

SPLTWN 

WINDOW 

SUBROUTINE  GSWKWN (WKID , XMIN , XMAX , YMIN , YMAX)  : 

GKS  routine  --  "SET  WORKSTATION  WINDOW" 

(See  GKS  manual  for  further  information.) 


Calling  Programs  -- 

SPLTWN 

WINDOW 

SUBROUTINE  GSWN (TNR , XMIN , XMAX , YMIN , YMAX)  : 

GKS  routine  --  "SET  WINDOW" 

(See  GKS  manual  for  further  information.) 


Calling  Programs  -- 

SPLTWN 

WINDOW 

SUBROUTINE  GTX(PX, PY, CHARS) : 

GKS  routine  --  "TEXT" 

(See  GKS  manual  for  further  information.) 


Calling  Programs  -- 

DISPLY 

MAPKEY 

MARKZP 

MENU11 

MENU 12 

MENU 20 

MENU 21 

MENU 2 2 

MENU23 

TOPMNU 

ZIPMAP 

ZOOMIN 

SUBROUTINE  HEADER: 
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This  subroutine  prints  a title  page  on  the  screen  when  the  user  enters  the 
system . 


Source  Code  Location  -- 
IOSUBS . FOR 

Programs  Called  -- 
None 

Calling  Programs  -- 
DRIVER 

SUBROUTINE  MAPKEY ( I ERR , MODIFY , TRN , PALETT , NCLRS , ID , MENU , MAXPLT , 

M , XCENT , YCENT , INDEX , PNT , ZI PCLR , XPLOT , YPLOT , 

LONG, PERM) : 

This  subroutine  displays  a color  key  for  the  current  zip  code  map.  It 
allows  the  user  to  locate  a zip  code  on  the  map  with  the  cursor  and  have  its 
five-digit  number  printed  on  the  screen.  (To  do  this,  a search  of  the 
centroid  array  is  done  to  find  the  closest  centroid  to  the  cursor  position.) 
If  the  current  map  is  for  modifying  POD  sites,  the  routine  also  allows  the 
colors  of  zip  codes  to  be  modified. 

Source  Code  Location  -- 
MAPSUBS . FOR 


Input  Variables 
MODIFY: 


TRN: 
PALETT : 
NCLRS: 

ID: 

MENU: 


M: 

XCENT(M) : 
YCENT (M) : 


LOGICAL 

Color  modification  indicator  -- 

MODIFY= . TRUE . if  the  array  of  zip  code  colors  is 
allowed  to  be  modified 
MODIFY=. FALSE . otherwise 
INTEGERS 

Transformation  number 
INTEGERS 

Palette  identifier  (1  or  2) 

INTEGERS 

Number  of  colors  in  menu 
(only  used  if  MODI FY= . TRUE . ) 

CHARACTERS 
District  number 
INTEGERS 

Menu  type  switch  -- 

MENU=0  for  general  coloring  menu 

MENU=1  for  menu  of  POD  types 

MENU=2  for  title  of  solution  map 

MENU=3  for  key  to  workload  map 

INTEGERS 

Number  of  zip  codes 
REALS 

Array  containing  x-coordinates  of  centroids, 
sorted  according  to  increasing  x and  y 
REALS 

Array  containing  y-coordinates  of  centroids, 
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INDEX(M) : 
PNT(M) : 
ZIPCLR(M) : 


MAXPLT : 


sorted  according  to  increasing  x and  y 
I NT EGER* 2 

Zip  code  index  array,  sorted  corresponding  to 

XCENT  and  YCENT  arrays 

INTEGERS 

Pointer  array,  sorted  corresponding  to  XCENT  and 

YCENT  arrays 

INTEGERS 

Zip  code  color  array  -- 

Positive  value:  Centroid  drawn  as  asterisk 
Negative  value:  Centroid  drawn  as  small  box 
INTEGER*4 

Maximum  number  of  plotting  points  allowed  in  a 
map  region 


Output  Variables  -- 
I ERR:  INTEGER*^ 

Error  flag  -- 
IERR=0  for  normal  return 
IERR=1  if  an  error  was  encountered 
ZIPCLR(M) : INTEGER*2 

Zip  code  color  array 
XPL0T(2*MAXPLT) : REAL*4 

Work  array  containing  x coordinates  of  points  to 
plot  in  a map  region 
YPLOT( 2*MAXPLT) : REAL*4 

Work  array  containing  y coordinates  of  points  to 
plot  in  a map  region 
LONG ( 2*MAXPLT) : REAL*4 

Work  array 

PERM(2*MAXPLT) : INTEGERS 

Work  array 


Programs  Called  -- 

BORDER 

CLSGKS 

CURSOR 

ERSMNU 

GFA 

GPL 

GPM 

GQNT 

GRQCH 

GRQLC 

GSELNT 

GSMK 

GSPLCI 

GSPMCI 

GSTXCI 

GTX 

MENU20 
MENU21 
MENU 2 2 
MENU23 
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REVERS 

SEARCH 

STYLE 

THIN 

Calling  Programs  -- 
DISPLY 

SUBROUTINE  MARKZP(ID ,M, ZIP5) : 

This  subroutine  allows  the  user  to  type  in  a zip  code  number  and  have  its 
location  marked  on  the  state  outline  map. 

Source  Code  Location  -- 
MAPSUBS . FOR 

Input  Variables  -- 
ID:  CHARACTERS 

District  number 
M:  INTEGERS 

Number  of  zip  codes 
ZIP5 (M)  : INTEGERS 

Array  of  five-digit  zip  codes,  in  original  sequential  order 

Programs  Called  -- 

GINST 

GPM 

GQCF 

GQCNTN 

GQMDS 

GQNT 

GRQST 

GSELNT 

GSMK 

GSPMCI 

GSSTM 

GSTXCI 

GTX 

REVERS 

Calling  Programs  -- 
DISPLY 

SUBROUTINE  HATCH  ( PALETT , INDEX)  : 

This  subroutine  sets  a polymarker  color  index  which  will  match  the 
corresponding  fill  area  color  index  (for  an  EGA  display  only).  (See  the  GKS 
manual  for  definitions  of  graphics  terms.) 

Source  Code  Location  -- 
GKSUTIL. FOR 

Input  Variables  -- 
PALETT:  INTEGERS 
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Palette  identifier 
INDEX:  INTEGER*4 

Index  (between  1 and  16)  of  fill  area  color 

Programs  Called  -- 
GSPMCI 

Calling  Programs  -- 
STEMAP 

SUBROUTINE  HENU11: 

This  subroutine  writes  a menu  of  display  options  on  the  left  side  of  the 
screen.  It  lists  the  meaning  of  the  function  keys  after  a state  outline 'map 
has  been  drawn. 

Source  Code  Location  -- 
MENUSUBS . FOR 

Programs  Called  -- 

GPL 

GQCNTN 

GSELNT 

GSPLCI 

GSTXCI 

GTX 

Calling  Programs  -- 
DISPLY 

SUBROUTINE  MENU 12 : 

This  subroutine  writes  a menu  of  display  options  on  the  left  side  of  the 
screen.  It  lists  the  meaning  of  the  function  keys  after  a zip  code  map  has 
been  drawn. 

Source  Code  Location  -- 
MENUSUBS . FOR 

Programs  Called  -- 

GPL 

GQCNTN 

GSELNT 

GSPLCI 

GSTXCI 

GTX 

Calling  Programs  -- 
DISPLY 

SUBROUTINE  MENU20: 

This  subroutine  writes  a color  key  on  the  left  side  of  the  screen.  It  lists 
the  colors  associated  with  the  function  keys. 
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Source  Code  Location 
MENUSUBS . FOR 


Programs  Called  -- 

BORDER 

BOX 

GFA 

GPL 

GQCNTN 

GSELNT 

GSPLCI 

GSTXCI 

GTX 

STYLE 

Calling  Programs  -- 
MAPKEY 

SUBROUTINE  MENU 21 : 

This  subroutine  writes  a color  key  on  the  left  side  of  the  screen.  It  lists 
the  colors  and  function  keys  associated  with  different  types  of  POD  sites. 

Source  Code  Location  -- 
MENUSUBS . FOR 

Programs  Called  -- 

BORDER 

BOX 

GFA 

GPL 

GQCNTN 

GSELNT 

GSPLCI 

GSTXCI 

GTX 

STYLE 

Calling  Programs  -- 
MAPKEY 

SUBROUTINE  MENU 2 2 : 

This  subroutine  displays  a title  for  the  solution  map  on  the  left  side  of 
the  screen. 

Source  Code  Location  -- 
MENUSUBS . FOR 

Programs  Called  -- 

BORDER 

GFA 

GPL 

GQCNTN 
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GSELNT 

GSPLCI 

GSTXCI 

GTX 

STYLE 

Calling  Programs  -- 
MAPKEY 

SUBROUTINE  MENU 2 3 : 

This  subroutine  writes  a color  key  on  the  left  side  of  the  screen.  It  lists 
the  colors  and  function  keys  used  for  displaying  workload. 

Source  Code  Location  -- 
MENUSUBS . FOR 

Programs  Called  -- 

BORDER 

GFA 

GPL 

GQCNTN 

GSELNT 

GSPLCI 

GSTXCI 

GTX 

STYLE 

Calling  Programs  -- 
MAPKEY 

SUBROUTINE  OPNGKS(WKID)  : 

This  subroutine  opens  GKS  with  one  workstation  of  type  "DISPLAY" . Error 
messages  will  be  written  to  a file  called  "ERRORS . GKS" . (See  the  GKS  manual 
for  definitions  of  graphics  terms.) 

Source  Code  Location  -- 
GKSUTIL. FOR 


Input  Variable  -- 
WKID:  INTEGERS 

Workstation  identifier 


Programs  Called  -- 

GACWK 

GINKS 

GOPKS 

GOPWK 


Calling  Programs  -- 

DISPLY 

DRIVER 
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SUBROUTINE  OPTION  ( 10 , DSTLIM , TXPWGT , IRSWCT , IMF , BMF , SWITCH , N CLASS , 

SQFT , MILCST , STAFF1 , STAFF2 , STAFF3 , PODCHG)  : 

This  subroutine  displays  the  default  options  for  the  cost  calculation  and 
allows  the  user  to  make  changes. 

Source  Code  Location  -- 
IOSUBS . FOR 


Input  Variables 
10: 

DSTLIM: 

TXPWGT : 

IRSWGT : 

IMF (2) : 

BMF (2) : 


NCLASS : 

SQFT: 

MILCST: 
STAFF1 : 
STAFF2 : 
STAFF3 : 


INTEGER*4 

Unit  number  defining  where  display  will  appear 
REAL*4 

Default  maximum  travel  distance  allowed  from  zip 
code  to  POD 
REAL* 4 

Default  weight  (nonnegative  real  number)  to  be 
assigned  to  taxpayer  travel  costs 
REAL* 4 

Default  weight  (nonnegative  real  number)  to  be 

assigned  to  IRS  travel  costs 

INTEGER*4 

Default  array  indicating  which  IRS  functions  are 
to  be  included  in  the  cost  calculation  for  IMF 
data  - - 

IMF(l):  Examination 
IMF(2):  Collection 
INTEGER*4 

Default  array  indicating  which  IRS  functions  are 
to  be  included  in  the  cost  calculation  for  BMF 
data  - - 

BMF(l):  Examination 
BMF(2):  Collection 
INTEGER*4 

Number  of  workload  columns  in  workload  file 
(not  including  display  columns) 

REAL* 4 

Default  office  space  required  per  TDI-TDA 
(square  feet) 

REAL*4 

Default  Mileage  cost  ($/mile) 

INTEGER*4 

Default  total  examination  staff  available 
INTEGER*4 

Default  total  collection  staff  available 
INTEGER*4 

Default  total  other  staff  available 


Output  Variables 
DSTLIM:  REAL* 4 

Maximum  travel  distance  allowed  from  zip  code  to 
POD 

TXPWGT : REAL*4 

Weight  (nonnegative  real  number)  to  be  assigned  to 
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taxpayer  travel  costs 
IRSWGT : REAL*4 

Weight  (nonnegative  real  number)  to  be  assigned  to 
IRS  travel  costs 
IMF(2)  : INTEGERS 

Array  indicating  which  IRS  functions  are  to  be 
included  in  the  cost  calculation  for  IMF  data 
BMF ( 2 ) : INTEGERS 

Array  indicating  which  IRS  functions  are  to  be 
included  in  the  cost  calculation  for  BMF  data 
SWITCH (NCLASS ) : INTEGERS 

Array  indicating  which  columns  of  the  workload 
file  are  to  be  included  in  the  cost  calculation 
REAL* 4 

Office  space  required  per  TDI-TDA  (square  feet) 
REAL* 4 

Mileage  cost  ($/mile) 

INTEGER*4 

Total  examination  staff  available 
INTEGER*4 

Total  collection  staff  available 
INTEGER*4 

Total  other  staff  available 
LOGICAL 

Flag  indicating  whether  POD  information  has  been 
changed 


SQFT : 

MILCST 

STAFF1 

STAFF2 

STAFF3 

PODCHG 


Programs  Called  -- 

READBF 

ROUND 

Calling  Programs  -- 

REPPRB 

SOLVE 

SUBROUTINE  ORDER (XINIT , YINIT , N , X , Y) : 

This  subroutine  reorders  the  interior  points  of  a zip  code  with  a hole  in  it 
so  that  the  connector  segment  joins  the  first  exterior  point  with  the 
closest  interior  point.  This  is  done  to  avoid  problems  which  arise  when  the 
GKS  shading  ("Fill  Area")  routine  is  used  with  a connector  segment  that 
crosses  the  interior  hole.  There  may  still  be  problems  with  zip  codes  which 
contain  several  holes . 

Source  Code  Location  -- 
GDTINST1 . FOR 

Input  Variables  -- 
XINIT:  REAL* 4 

X coordinate  of  initial  exterior  connecting  point 
YINIT:  REAL* 4 

Y coordinate  of  initial  exterior  connecting  point 
N:  INTEGER*4 

Number  of  interior  points  (boundary  of  hole) 
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X(N) : REALS 

Array  containing  x coordinates  of  interior  points 
Y(N) : REALS 

Array  containing  y coordinates  of  interior  points 

Output  Variables  -- 
X(N):  REALS 

Reordered  array  of  interior  x coordinates 
Y(N) : REALS 

Reordered  array  of  interior  y coordinates 

Programs  Called 
None 

Calling  Programs  -- 
ZIPBND 

SUBROUTINE  OUTLIN(IERR,IDfXNIN,YMIN,XMAX,YMAXfMAXPTS,X,Y)  : 

This  subroutine  converts  the  GDT  state  boundary  file  to  binary  form, 
thinning  out  the  data  in  the  process. 

Source  Code  Location  -- 
GDTINST1 . FOR 

Input  Variables  -- 
ID:  CHARACTERS 

Two-digit  district  identification  number 
MAXPTS : INTEGERS 

Maximum  number  of  points  allowed  in  a map  region 

Output  Variables  -- 
I ERR:  INTEGERS 

Error  flag  -- 
IERR=0  for  normal  return 
IERR=1  if  an  error  was  encountered 
XMIN : REALS 

Minimum  x coordinate  of  state  map 

YMIN : REALS 

Minimum  y coordinate  of  state  map 

XMAX : REALS 

Maximum  x coordinate  of  state  map 

YMAX : REALS 

Maximum  y coordinate  of  state  map 

X( MAXPTS):  REALS 

Work  array  containing  x coordinates  of  a map  region 
Y( MAXPTS):  REALS 

Work  array  containing  y coordinates  of  a map  region 

Programs  Called  -- 
None 

Calling  Programs  -- 
GDTINST1 
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SUBROUTINE  PAUSE: 


This  subroutine  requests  the  user  to  press  "Enter"  to  continue.  It  is  used 
following  error  messages  to  allow  the  user  time  to  see  the  message. 

Source  Code  Location  -- 
IOSUBS .FOR 

Programs  Called 
None 


Calling  Programs  -- 

CENSRT 

PODMAP 

REPSOL 

SOLMAP 

SOLVE 

WRKMAP 

SUBROUTINE  PODMAP (IERR , ID , PODSET , M , XCENT , YCENT , INDEX , PNT , 

ZI P5 , ZI PCLR , MAXPLT , XPLOT , YPLOT , LONG , PERM) : 

This  subroutine  initializes  the  display  of  a map  of  current  and  potential 
POD  sites.  It  is  executed  when  the  user  chooses  "F3  - Display  or  modify 
initial  POD  sites"  from  the  top  menu.  First  it  reads  the  file  PODSITE.id 
(or  NEWPOD.id)  to  find  which  zip  codes  are  allowed  to  be  POD  sites  and  which 
zip  codes  currently  are  POD  sites.  Color  #1  (background)  is  assigned  to  zip 
codes  which  cannot  be  POD  sites,  color  #2  is  assigned  to  potential  POD 
sites,  and  color  #3  is  assigned  to  current  POD  sites.  (Note:  A negative 
color  number  indicates  that  the  centroid  will  be  drawn  as  a small  box; 
otherwise  the  centroid  is  an  asterisk.)  Then  these  colors  are  passed  in  an 
array  to  the  subroutine  DISPLY,  which  draws  the  map  and  lets  the  user  change 
the  colors.  The  new  colors  are  returned  in  the  original  array.  Color  #4  in 
the  new  array  indicates  a zip  code  which  the  user  has  made  a fixed  POD  site. 

Source  Code  Location  -- 
DRIVER. FOR 


Input  Variables 
ID: 

M: 

PODSET: 

XCENT (M) : 
YCENT(M) : 
INDEX(M) : 


CHARACTERS 
District  number 
INTEGERS 

Number  of  zip  codes 
LOGICAL 

Flag  indicating  whether  or  not  POD  colors  have 

been  previously  set 

REALS 

Array  containing  x-coordinates  of  centroids, 
sorted  according  to  increasing  x and  y 
REALS 

Array  containing  y-coordinates  of  centroids, 
sorted  according  to  increasing  x and  y 
INTEGERS 

Zip  code  index  array  -- 
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PNT(M) : 


ZIP5 (M) : 
ZIPCLR(M) : 


MAXPLT : 


INDEX(I)  is  the  original  index  of  the  zip  code 
with  centroid  (XCENT(I) ,YCENT(I) ) before  sorting 
I NT EGER* 2 
Pointer  array  -- 

PNT(I)  points  to  the  beginning  of  information  on 
the  zip  code  with  centroid  (XCENT(I) ,YCENT(I) ) in 
the  zip  code  boundary  file 
INTEGERS 

Array  of  five-digit  zip  codes,  in  original 

sequential  order 

INTEGER*2 

Zip  code  color  array  for  POD  site  types, 

if  previously  set 

INTEGERS 

Maximum  number  of  plotting  points  allowed  in  a 
map  region 


Output  Variables  -- 
I ERR : INTEGERS 

Error  flag  -- 
IERR=0  for  normal  return 
IERR=1  if  an  error  was  encountered 
POD SET:  LOGICAL 

Flag  indicating  whether  or  not  POD  colors  were 
successfully  set 
ZIPCLR(M) : INTEGER*2 

Zip  code  color  array  for  POD  site  types 
XPL0T(2*MAXPLT) : REAL*4 

Work  array  containing  x coordinates  of  points  to 
plot  in  a map  region 
YPLOT ( 2*MAXPLT) : REAL*4 

Work  array  containing  y coordinates  of  points  to 
plot  in  a map  region 
L0NG(2*MAXPLT) : REAL* 4 

Work  array 

PERM( 2*MAXPLT) : INTEGER*2 

Work  array 


Programs  Called  -- 

DISPLY 

PAUSE 

Calling  Programs  -- 
DRIVER 

SUBROUTINE  RANGES (RNGSET.NRANGE, RANGE, WRKMIN , WRKMAX)  : 

This  subroutine  sets  ranges  for  the  workload  display  map  and  allows  the  user 
to  make  changes. 

Source  Code  Location  -- 
IOSUBS . FOR 

Input  Variables  -- 
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RNGSET : 

LOGICAL 

Flag  indicating  whether  or  not  ranges  have  been 
previously  set 

NRANGE : 

INTEGERM 

Number  of  ranges  for  previous  workload  display 

RANGE (0 : NRANGE) : 

REALM 

Array  containing  range  limits  for  previous 
workload  display 

WRKMIN : 

INTEGERM 

Minimum  workload  value 

WRKMAX: 

INTEGERM 

Maximum  workload  value 

Output  Variables 

RNGSET: 

LOGICAL 

Flag  indicating  that  ranges  have  been  set 

NRANGE: 

INTEGERM 

Number  of  ranges  for  workload  display 

RANGE(0: NRANGE) : 

REALM 

Array  containing  range  limits  -- 

The  lower  limit  of  the  Ith  range  is  RANGE(I-l) 

and  the  upper  limit  is  RANGE(I) 

Programs  Called  -- 

READBF 

ROUND 

Calling  Programs  -- 
WRKMAP 

SUBROUTINE  READBF (I ERR , MXITMS , NITEMS , ITEM) : 

This  subroutine  reads  an  input  string  from  the  terminal  into  a buffer  and 
tries  to  convert  it  to  a list  of  real  numbers.  The  items  in  the  string  must 
be  separated  by  spaces  or  commas. 

Source  Code  Location  -- 
IOSUBS . FOR 

Input  Variable  -- 
MXITMS:  INTEGERS 

Maximum  allowed  number  of  items  in  input  string 

Output  Variables  -- 
I ERR : INTEGERS 

Error  flag  -- 
IERR=0  for  normal  return 
IERR="1  if  an  error  was  encountered 

NITEMS:  INTEGERS 

Number  of  items  in  input  string 

ITEM(NITEMS) : REALM 

Array  containing  list  of  real  numbers  in  input 
string 
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Programs  Called  -- 
None 


Calling  Programs  -- 

GEOFAC 

OPTION 

RANGES 

SOLVE 

WRKMAP 

SUBROUTINE  REPFIL(ID)  : 

This  subroutine  initializes  the  report  file  REPORT. id.  Either  a new  report 
file  is  created  or  information  is  appended  to  an  existing  report  file.  A 
report  header  is  written  giving  the  date  and  time.  The  report  file  is 
assigned  to  unit  12,  which  remains  open  after  returning  from  the  subroutine. 

Source  Code  Location  -- 
IOSUBS . FOR 

Input  Variable  -- 
ID:  CHARACTERS 

District  number 

Programs  Called  -- 

CONVRT 

GETDAT 

GETTIM 


Calling  Programs  -- 
DRIVER 

SUBROUTINE  REPPRB  (M , ZIPCLR , ZIP5  , DSTLIM , IRSWT , TXPWT , IMFFNC , BMFFNC , 

NREC , DIFZIP , DIFPOD , DIFFAC , FXCOST , CSQRFT , SQFT , 
MILCST , IRSFCT , TXPFCT , STFFCT , SWITCH , N CLASS , 
STAFFl , STAFF2  , STAFF3  , PODCHG)  : 


This  subroutine  writes  information  on  the  problem  initialization  into  the 
report  file. 


Source  Code  Location  -- 
IOSUBS. FOR 


Input  Variables 
M: 

ZIPCLR(M) : 

ZIP5 (M) : 

DSTLIM: 


IRSWT: 


INTEGERS 

Number  of  zip  codes 
INTEGERS 

Zip  code  color  array  for  POD  site  types 
INTEGERS 

Array  of  five-digit  zip  codes 
REALS 

Maximum  travel  distance  allowed  from  zip  code  to 
POD 

REALS 
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TXPWT: 
IMFFNC(2) : 

BMFFNC ( 2 ) : 

NREC : 

DIFZIP (NREC) : 

DIFPOD(NREC) : 

DIFFAC (NREC) : 
FXCOST(NPOD) : 
CSQRFT(NPOD) : 

SQFT : 

MILCST : 

IRSFCT(NCLASS) 
TXPFCT(NCLASS) 
STFFCT(NCLASS) 
SWITCH ( NCLAS S ) 

NCLASS : 

STAFF1 : 

STAFF2 : 

STAFF3 : 

PODCHG : 


Weight  assigned  to  IRS  travel  costs 
REAL* 4 

Weight  assigned  to  taxpayer  travel  costs 
INTEGERS 

Array  indicating  which  IRS  functions  are  included 

in  the  cost  calculation  for  IMF  data 

INTEGER*4 

Array  indicating  which  IRS  functions  are  included 

in  the  cost  calculation  for  BMF  data 

INTEGER*4 

Number  of  non-unit  travel  difficulty  factors 
INTEGER*4 

Five-digit  zip  code  array  for  use  with  travel 

difficulty  factors 

INTEGER*4 

POD  zip  code  array  for  use  with  travel  difficulty 

factors 

REAL*4 

Array  of  travel  difficulty  factors 
REAL*4 

Array  containing  fixed  costs  of  POD  sites 
REAL* 4 

Array  containing  yearly  rental  costs  per  square 

foot  for  POD  site  office  space 

REAL*4 

Office  space  required  per  TDI-TDA  (square  feet) 
REAL* 4 

Mileage  cost  ($/mile) 

REAL* 4 

Array  of  IRS  trip  factors 
REAL*4 

Array  of  taxpayer  trip  factors 
REAL* 4 

Array  of  staffing  factors 
INTEGER*2 

Array  indicating  which  columns  of  the  workload 
file  are  included  in  the  cost  calculation 
INTEGER*4 

Number  of  workload  columns  in  workload  file 
(not  including  display  columns) 

INTEGER*4 

Total  examination  staff  available 
INTEGER*4 

Total  collection  staff  available 
INTEGER*4 

Total  other  staff  available 
LOGICAL 

Flag  indicating  whether  POD  information  has 
been  changed 


Programs  Called  -- 
OPTION 


i 


Calling  Programs  -- 
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SOLVE 


SUBROUTINE  REPSOL( I ERR , ZIP5 , PODLST , M , ZIPIND , ZIPCLR , ID , 

IMFEXM , BMFEXM , TDICOL , TDACOL , 

IMFEX2 , BMFEX2 , TDIC02 , TDAC02 ) : 


This  subroutine  is  executed  when  the  user  chooses  "F6  - Report  zip  code  and 
staff  assignments"  from  the  top  menu.  It  writes  information  on  the  problem 
solution  into  the  report  file. 

Source  Code  Location  -- 
IOSUBS . FOR 


Input  Variables  -- 
ZIP5  (M)  : INTEGERS 

Array  of  five-digit  zip  codes,  in  original  sequential 
order 

M:  INTEGER*4 

Number  of  zip  codes 
ID:  CHARACTER*2 

District  number 

Output  Variables  -- 
I ERR:  INTEGERS 


PODLST(NPOD) : 
ZIPIND (M) : 
ZIPCLR(M) : 
IMFEXM(NPOD) : 
BMFEXM (NPOD) : 
TDICOL(NPOD) : 
TDACOL(NPOD) : 


Error  flag  -- 

IERR=0  for  normal  return 

IERR=1  if  an  error  was  encountered 

INTEGER*2 


Work  array  containing 
INTEGERS 

Work  array  containing 
INTEGERS 

Work  array  containing 
REAL*4 

Work  array  containing 
REAL*4 

Work  array  containing 
REAL*4 

Work  array  containing 
REAL* 4 

Work  array  containing 


POD  indices 
POD  assignments 
pointers  to  PODLST 
adjusted  POD  workloads 
adjusted  POD  workloads 
adjusted  POD  workloads 
adjusted  POD  workloads 


IMFEX2 (NPOD) : REAL*4 

Work  array 
BMFEX2 (NPOD) : REAL*4 

Work  array 
TDIC02 (NPOD) : REAL* 4 

Work  array 
TDAC02 (NPOD) : REAL*4 

Work  array 

Programs  Called  - - 


containing 

containing 

containing 

containing 


unadjusted 

unadjusted 

unadjusted 

unadjusted 


POD  workloads 
POD  workloads 
POD  workloads 
POD  workloads 


PAUSE 


Calling  Programs  -- 
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DRIVER 


FUNCTION  REVERS (X , MIN , MAX) : 

This  function  reverses  the  direction  of  a coordinate  axis.  (This  is 
necessary  because  the  x coordinates  in  the  GDT  files  increase  from  right  to 
left,  but  GKS  assumes  that  they  increase  from  left  to  right.) 

Source  Code  Location  -- 
MAPSUBS . FOR 

Input  Variables  -- 
X:  REAL* 4 

Value  to  be  reversed 
MIN : REAL* 4 

Minimum  value  of  axis  to  be  reversed 
MAX : REAL*4 

Maximum  value  of  axis  to  be  reversed 

Output  Variable  -- 
REVERS:  REAL*4 

Reversed  value  of  x 

Programs  Called  -- 
None 

Calling  Programs  -- 

MAPKEY 

MARKZP 

STEMAP 

ZIPMAP 

ZOOMIN 

FUNCTION  ROUND (X): 

This  subroutine  rounds  a real  number  to  the  nearest  integer.  Numbers  ending 
in  .5  are  truncated. 

Source  Code  Location  -- 
IOSUBS . FOR 

Input  Variable  -- 
X : REAL*4 

Real  number 

Output  Variable  -- 
ROUND:  INTEGER*4 

Rounded  value  of  x 

Programs  Called  -- 
None 

Calling  Programs  -- 
OPTION 


I 
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RANGES 

WRKMAP 


SUBROUTINE  SEARC1I(XFT , YPT,M,X, Y, POS)  : 

This  subroutine  searches  the  list  of  sorted  centroids  to  find  the  centroid 
closest  to  a given  point.  A binary  search  is  done  to  find  the  nearest  x 
coordinate,  and  then  a sequential  search  is  done  to  find  the  nearest  y 
coordinate. 

Source  Code  Location  -- 
MAPSUBS . FOR 

Input  Variables  -- 
XPT : REAL*4 

X-coordinate  of  point  to  be  located 
YPT : REAL*4 

Y-coordinate  of  point  to  be  located 
M:  INTEGERS 

Number  of  zip  codes 
X(M) : REAL*4 

Array  containing  x- coordinates  of  centroids, 
sorted  according  to  increasing  x and  y 
Y(M) : REAL* 4 

Array  containing  y-coordinates  of  centroids, 
sorted  according  to  increasing  x and  y 

Output  Variable  -- 
POS : INTEGERS 

Position  of  (XPT, YPT)  in  centroid  list 
(i.e.  (XPT , YPT)=(X(POS) , Y(POS) ) ) 

POS=0  if  point  was  not  found 

Programs  Called  -- 
None 

Calling  Programs  -- 
MAPKEY 

SUBROUTINE  SETCOL(WKID,PALETT)  : 

This  subroutine  defines  the  colors  to  be  used  by  the  display  device.  The 
type  of  display  device  in  use  is  determined  by  a call  to  the  GKS  routine 
GQCF  which  returns  the  number  of  colors  available  on  the  current  device 
driver.  For  a CGA  display  in  medium-resolution  four-color  mode,  this 
subroutine  sets  palette  two  with  a blue  background.  For  an  EGA  display,  it 
sets  sixteen  colors  in  one  of  two  possible  palettes.  (See  the  GKS  manual 
for  definitions  of  graphics  terms.) 

Source  Code  Location  -- 
GKSUTIL. FOR 

Input  Variable  -- 
WKID : INTEGERS 
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Workstation  identifier 
PALETT:  INTEGER*2 

Palette  identifier  (1  or  2)  -- 
PALETT=1:  16  distinct  colors 

PALETT=2 : Colors  4 through  9 are  shades  of  green 
(Palett  is  not  used  in  medium  resolution  mode) 

Programs  Called  -- 

GQCF 

GSCR 

Calling  Programs  -- 

SPLTWN 

WINDOW 

SUBROUTINE  SOLMAP  ( I ERR , ID , M , XCENT , YCENT , INDEX , PNT , ZIPCLR , 

ZIP5 , MAXPLT , XPLOT , YPLOT , LONG , PERM)  : 

This  subroutine  initializes  the  display  of  a solution  map.  It  is  executed 
when  the  user  chooses  "F5  - Display  optimal  POD  locations"  from  the  top 
menu.  It  checks  the  solution  file  SOLUTION. id  to  see  whether  the  graph- 
coloring algorithm  was  used  by  the  solver.  (This  algorithm  is  used  only  if 
an  input  file  ADJACENT. id  is  present.)  If  graph  coloring  was  not  used,  then 
only  zip  codes  which  are  POD  sites  (as  determined  by  the  solution)  will  be 
colored  on  the  map  (using  color  #3);  all  other  zip  codes  will  be  in  the 
background  color  (color  #1).  (Note:  A negative  color  number  indicates  that 
the  centroid  will  be  drawn  as  a small  box;  otherwise  the  centroid  is  an 
asterisk.)  If  graph  coloring  was  used,  then  a color  for  each  zip  code  is 
read  from  the  solution  file  (the  color  number  is  increased  by  one  to  avoid 
using  the  background  color) . The  resulting  map  will  show  a POD  and  its 
assigned  zip  codes  all  in  the  same  color.  The  subroutine  DISPLY  is  called 
to  draw  the  map . 

Source  Code  Location  -- 
DRIVER. FOR 


Input  Variables 
ID: 

M: 

XCENT (M) : 

YCENT (M) : 
INDEX(M) : 

PNT(M) : 


CHARACTERS 
District  number 
INTEGERS 

Number  of  zip  codes 
REALS 

Array  containing  x-coordinates  of  centroids, 
sorted  according  to  increasing  x and  y 
REAL* 4 

Array  containing  y- coordinates  of  centroids, 
sorted  according  to  increasing  x and  y 
INTEGER*2 

Zip  code  index  array  -- 

INDEX(I)  is  the  original  index  of  the  zip  code 
with  centroid  (XCENT(I) ,YCENT(I) ) before  sorting 
INTEGER*2 
Pointer  array  -- 

PNT(I)  points  to  the  beginning  of  information  on 
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the  zip  code  with  centroid  (XCENT(I) , YCENT(I) ) in 
the  zip  code  boundary  file 
ZIP5 (M)  : INTEGERS 

Array  of  five-digit  zip  codes 
MAXPLT : INTEGERS 

Maximum  number  of  plotting  points  allowed  in  a 
map  region 


Output  Variables 
I ERR: 


ZIPCLR(M) : 

XPLOT ( 2*MAXPLT) : 

YPLOT ( 2*MAXPLT ) : 

LONG ( 2 *MAXPLT ) : 
PERM ( 2*MAXPLT ) : 


INTEGER*4 

Error  flag  -- 

IERR-0  for  normal  return 

IERR-1  if  an  error  was  encountered 

INTEGER*2 

Zip  code  color  array 
REAL*4 

Work  array  containing  x coordinates 

plot  in  a map  region 

REAL*4 

Work  array  containing  y coordinates 

plot  in  a map  region 

REAL*4 

Work  array 

INTEGER*2 

Work  array 


of  points 
of  points 


to 


to 


Programs  Called  - - 

DISPLY 

PAUSE 


Calling  Programs  -- 
DRIVER 

SUBROUTINE  SOLVE  ( I ERR,  ID , POD  SET , MAXPOD , PODZIP , XPOD , YPOD , 

M , HOLD , FXCOST , CSQRFT , TRVDIF,  ZIPCLR , ZIP5 , JCOEF , 

COST , MAXDIF , DIFZIP , DIFPOD , DIFFAC) : 

This  subroutine  allows  the  user  to  set  parameters  to  initialize  a location 
problem  and  then  calculates  costs  which  are  passed  to  the  solution  procedure 
SOLVER.EXE.  It  is  executed  when  the  user  chooses  "F4  - Solve  for  optimal 
POD  locations"  from  the  top  menu.  First,  several  parameters  such  as  cost 
per  mile,  maximum  travel  distance,  and  staff  totals  are  read  from  the  file 
PODSITE.id.  Then  opening/closing  costs  and  office  rental  costs  for  each  POD 
site  are  read.  If  any  POD  sites  exist  which  are  not  in  the  file,  the  user 
is  asked  to  enter  the  costs.  Then  trip  factors  and  staffing  factors  are 
read  from  the  file  WORKLOAD. id.  The  user  is  allowed  to  set  weights  for  IRS 
and  taxpayer  costs,  to  turn  categories  of  workload  on  or  off,  to  change  the 
distance  limit  and  staff  totals,  and  to  set  travel  difficulty  factors.  The 
parameter  settings  are  summarized  in  the  report  file  REPORT. id. 

After  all  parameters  have  been  set,  the  program  proceeds  to  calculate  costs 
of  assigning  zip  codes  to  POD  sites.  These  costs  are  passed  to  the  PASCAL 
solution  procedure  in  the  unformatted  sequential  file  TRANSFER. id.  For  each 
zip  code,  the  program  finds  all  possible  POD  sites  (current,  potential  and 
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fixed)  within  the  specified  distance  limit  and  calculates  the  cost  of  each 
assignment  using  the  function  COSTFN.  The  assignments  are  then  sorted  in 
order  of  decreasing  cost;  if  a zip  code  is  a possible  POD  site,  its  cost  is 
last  in  the  list.  The  list  of  costs  and  POD  sites  for  a particular  zip  code 
is  written  as  one  record  of  the  file  TRANSFER. id.  The  type  of  the  zip  code 
(i.e.,  whether  it  is  a potential  POD  site,  a fixed  POD  site,  etc.)  is  also 
included  in  the  record.  The  record  is  padded  with  zeroes  to  make  the  file 
readable  by  a PASCAL  program.  If,  for  some  zip  code,  there  are  no  possible 
POD  sites  within  the  distance  limit,  an  error  message  will  appear  on  the 
screen.  Otherwise,  the  subroutine  is  exited  and  control  passes  to  the 
solution  procedure.  (The  solution  algorithm  is  described  in  "The  Internal 
Revenue  Service  Post-of-Duty  Location  Modeling  System:  Programmer's  Manual 
for  PASCAL  Solver" . ) 

Source  Code  Location  -- 

DRIVER. FOR 


Input  Variables 
ID: 

PODSET: 


MAXPOD: 

M: 

ZIPCLR(M) : 
ZIP5 (M) : 


MAXDIF: 


CHARACTERS 
District  number 
LOGICAL 

Flag  indicating  whether  or  not  POD  colors  have 

been  previously  set 

INTEGERS 

Maximum  possible  number  of  POD  sites 
INTEGERS 

Number  of  zip  codes 
INTEGERS 

Zip  code  color  array  for  POD  site  types, 

if  previously  set 

INTEGERS 

Array  of  five-digit  zip  codes,  in  original 

sequential  order 

INTEGERS 

Maximum  number  of  non-unit  travel  difficulty 
factors 


Output  Variables 
I ERR: 

PODZIP (NPOD) : 
XPOD(NPOD) : 


YPOD(NPOD) : 

HOLD(NPOD) : 
FXCOST (NPOD) 


INTEGERS 

Error  flag  -- 

IERR=0  for  normal  return 

IERR=1  if  an  error  was  encountered 

INTEGERS 

Array  containing  zip  code  indices  of  POD  sites 
REAL* 4 

Array  containing  x- coordinates  of  centroids  of 

POD  sites 

REALS 

Array  containing  y-coordinates  of  centroids  of 

POD  sites 

REALS 

Work  array 

REALS 

Array  containing  fixed  costs  of  POD  sites 
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CSQRFT(NPOD) : 
TRVDIF(NPOD) : 
ZIPCLR(M) : 


JCOEF(NPOD) : 
COST(NPOD) : 
DIFZIP (NREC) : 

DIFPOD(NREC) : 

DIFFAC(NREC) : 


REAL*4 

Array  containing  yearly  rental  costs  per  square 

foot  for  POD  site  floor  space 

REAL*4 

Work  array  containing  travel  difficulty  factors 
from  a zip  code  to  all  possible  POD  sites 
INTEGERS 

Zip  code  color  array  for  POD  site  types 
-1  <=>  Standard  zip  code 
-2  <->  Potential  POD  site 

-3  <->  Newly  added  currently  existing  POD  site 

3 <«>  Standard  currently  existing  POD  site 
-4  <«>  Fixed  POD  site  with  opening  cost 

4 <=>  Fixed  POD  site  without  closing  cost 
I NT EGER* 2 

Work  array  containing  POD  indices  for  a zip  code 
REAL* 8 

Work  array  containing  POD  costs  for  a zip  code 
INTEGER*4 

Five-digit  zip  code  array  for  use  with  travel 

difficulty  factors 

INTEGER*4 

POD  zip  code  array  for  use  with  travel  difficulty 

factors 

REAL*4 

Array  of  travel  difficulty  factors  -- 
DIFFAC(I)  is  the  factor  associated  with  zip  code 
DIFZIP ( I ) and  POD  site  DIFPOD(I) 


Programs  Called  -- 

COSTFN 

GCDIST 

GEO FAC 

OPTION 

PAUSE 

READBF 

REPPRB 

SORT 


Calling  Programs  -- 
DRIVER 

SUBROUTINE  SORT (M , X , Y , INDEX , PNT) : 

This  subroutine  uses  a heapsort  algorithm  to  sort  the  centroids  according  to 
increasing  x and  y coordinates.  It  is  also  used  to  sort  other  arrays.  For 
a description  of  the  heapsort  algorithm,  see,  for  example,  An  Introduction 
to  Data  Structures  with  Applications  by  J . P.  Tremblay  and  P.  G.  Sorenson 
(McGraw-Hill,  1976,  p.  475). 

Source  Code  Location  -- 
DRIVER. FOR 

Input  Variables  -- 
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M: 

X(M): 

Y(M): 

INDEX(M) 

PNT(M) : 


INTEGER*4 

Number  of  zip  codes 
REAL*4 

Array  containing  x-coordinates  of  centroids 
REAL*4 

Array  containing  y-coordinates  of  centroids 
INTEGERS 

Zip  code  index  array  -- 
INDEX(I)=I  on  input 
I NT EGER* 2 
Pointer  array  -- 

PNT(I)  points  to  the  beginning  of  information  on  the 
Ith  zip  code  in  the  zip  code  boundary  file 


Output  Variables  -- 
X(M) : REAL* 4 

Array  containing  x-coordinates  of  centroids, 
sorted  according  to  increasing  x and  y 
Y (M) : REAL*4 

Array  containing  y-coordinates  of  centroids, 
sorted  according  to  increasing  x and  y 
INDEX(M) : INTEGER*2 


Zip  code  index  array  -- 

INDEX(I)  is  the  original  index  of  the  zip  code  with 
centroid  (XCENT(I) ,YCENT(I) ) before  sorting 
PNT (M) : INTEGER*2 

Pointer  array,  sorted  corresponding  to  XCENT  and 
YCENT  arrays 


Programs  Called  -- 
None 


Calling  Programs  -- 

CENSRT 

SOLVE 

THIN 


SUBROUTINE  SPLTWN (WKID , RTRN , PALETT , XMIN , XMAX , YMIN , YMAX) : 

This  subroutine  sets  up  a split  window  and  viewport  (designed  for  a menu  on 
the  left  side  and  a map  on  the  right  side) . World  coordinates  for  the  left 
side  must  be  between  0 and  1 and  use  transformation  number  7.  The  width  of 
the  left  window  is  set  to  be  the  width  of  eight  characters.  World 
coordinates  and  a transformation  number  for  the  right  side  must  be  specified 
by  the  programmer.  The  aspect  ratio  of  the  map  is  adjusted  for  latitude- 
longitude  data.  (See  the  GKS  manual  for  definitions  of  graphics  terms.) 

Source  Code  Location  -- 

GKSUTIL. FOR 


Input  Variables  -- 
WKID:  INTEGER*2 

Workstation  identifier 
RTRN:  INTEGER*2 
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Right  transformation  number  (between  1 and  6) 
PALETT:  INTEGER*2 

Palett  identifier  (1  or  2) 

XMIN : REALS 

Smallest  x value  of  right  world  coordinates 
XMAX : REALS 

Largest  x value  of  right  world  coordinates 
YMIN : REALS 

Smallest  y value  of  right  world  coordinates 
YMAX : REALS 

Largest  y value  of  right  world  coordinates 

Programs  Called  -- 

BORDER 

GCDIST 

GCLRWK 

GQMDS 

GQTXX 

GSELNT 

GSVP 

GSWKVP 

GSWKWN 

GSWN 

SETCOL 

WINDOW 


Calling  Programs  -- 

STEMAP 

ZIPMAP 

SUBROUTINE  S TEMAP ( I ERR, TRN, PALETT, ID, XMIN, XMAX, YMIN , YMAX, 

M , XCENT , YCENT , INDEX , ZIPCIH , MAXPLT , XPLOT , YPLOT , 

LONG, PERM) : 

This  subroutine  draws  a state  map,  showing  the  outline  of  the  state  and 
centroids  of  zip  codes.  (Zip  code  boundaries  are  not  drawn.)  The  state 
border  is  read  from  the  file  OUTLIN.id. 


Source  Code  Location  -- 
MAPSUBS . FOR 


Input  Variables 
TRN: 

PALETT : 

ID: 

M: 

XCENT (M) : 

YCENT (M) : 


INTEGER*2 

Transformation  number 
I NT EGER* 2 

Palette  identifier  (1  or  2) 

CHARACTERS 
District  number 
INTEGERS 

Number  of  zip  codes 
REALS 

Array  containing  x-coordinates  of  centroids 
REALS 

Array  containing  y-coordinates  of  centroids 
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INDEX(M) : 
ZIPCLR(M) : 


MAXPLT: 


I NT EGER* 2 

Zip  code  index  array 
I NT EGER* 2 

Zip  code  color  array  -- 

Positive  value:  Centroid  drawn  as  asterisk 
Negative  value:  Centroid  drawn  as  small  box 
INTEGER*4 

Maximum  number  of  plotting  points  allowed  in  a 
map  region 


Output  Variables 
I ERR: 


XMIN : 

XMAX: 

YMIN : 

YMAX: 

XPLOT (2*MAXPLT) : 

YPLOT ( 2*MAXPLT ) : 

LONG ( 2*MAXPLT ) : 
PERM ( 2*MAXPLT ) : 


INTEGER*4 

Error  flag  -- 

IERR*=0  for  normal  return 

IERR=1  if  an  error  was  encountered 

REAL* 4 

X coordinate  of  lower  left  corner  of  map 
REAL*4 

X coordinate  of  upper  right  corner  of  map 
REAL* 4 

Y coordinate  of  lower  left  corner  of  map 
REAL*4 

Y coordinate  of  upper  right  corner  of  map 
REAL* 4 

Work  array  containing  x coordinates  of  points  to 

plot  in  a map  region 

REAL*4 

Work  array  containing  y coordinates  of  points  to 

plot  in  a map  region 

REAL*4 

Work  array 

INTEGER*2 

Work  array 


Programs  Called  -- 

BEEP 

CLSGKS 

GPL 

GPM 

GQCF 

GSMK 

GSPLCI 

GSPMCI 

MATCH 

REVERS 

SPLTWN 

THIN 


Calling  Programs  -- 
DISPLY 

SUBROUTINE  STYLE (I ERR ,VKID , PALETT , INDEX) : 
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This  subroutine  sets  one  of  sixteen  area-filling  interior  styles.  For  a CGA 
display  in  medium-resolution  four-color  mode,  the  style  is  either  a solid 
color  or  a cross-hatch  pattern.  For  an  EGA  display,  the  style  is  always  a 
solid  color.  (See  the  GKS  manual  for  definitions  of  graphics  terms.) 

Source  Code  Location  -- 
GKSUTIL. FOR 

Input  Variables  -- 
WKID:  INTEGERS 

Workstation  identifier 
PALETT:  I NT EGER* 2 

Palette  identifier  (1  or  2)  -- 
PALETT-1:  16  distinct  colors 

PALETT=2 : 6 shades  of  green  plus  10  other  colors 
(Palett  is  not  used  in  medium  resolution  mode) 

INDEX:  INTEGER*^ 

Index  (between  1 and  16)  of  desired  interior  style 

Output  Variable  -- 
I ERR:  INTEGER*4 

Error  flag  -- 

IERR=0  for  normal  return 

IERR=1  if  an  error  was  encountered 

Programs  Called  -- 

CLSGKS 

GQCF 

GSFACI 

GSFAIS 

GSFASI 

Calling  Programs  -- 

ERSMNU 

MAPKEY 

MENU 20 

MENU21 

MENU22 

MENU 2 3 

ZIPMAP 

SUBROUTINE  THIN (XPLOT, YPLOT, NPTS  .MAXPLT,  IPTS  .WORK,  PERM)  : 

This  subroutine  thins  zip  code  boundaries  which  have  more  than  the  maximum 
allowed  number  of  plotting  points. 

Source  Code  Location  -- 
MAPSUBS . FOR 

Input  Variables  -- 
XPLOT (NPTS):  REAL* 4 

Array  containing  x coordinates  of  boundary  points 
YPLOT (NPTS):  REAL*4 

Array  containing  y coordinates  of  boundary  points 
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NPTS : I NT EGER* 4 

Number  of  boundary  points 

MAXPLT : INTEGER*4 

Maximum  number  of  boundary  points  to  be  plotted 
IPTS : INTEGER*4 

Number  of  interior  points 


Output  Variables  -- 
XPLOT(NPTS) : REAL* 4 

Array  containing  x coordinates  of  thinned  boundary 
points 

YPLOT(NPTS) : REAL*4 

Array  containing  y coordinates  of  thinned  boundary 
points 

NPTS : INTEGER*4 


Number  of  thinned  boundary  points 
W0RK(2*MAXPLT) : REAL*4 

Work  array 

PERM(2*MAXPLT) : INTEGER*2 
Work  array 


Programs  Called  -- 
SORT 


Calling  Programs  -- 

MAPKEY 

STEMAP 

ZIPMAP 


SUBROUTINE  TOPMNU: 

This  subroutine  writes  the  text  for  the  top-level  menu  on  the  screen.  The 
format  of  the  menu  is  slightly  different  depending  on  whether  a CGA  or  an 
EGA  display  is  being  used.  This  is  determined  by  calling  the  GKS  routine 
GQCF  which  finds  the  number  of  colors  available  on  the  current  device 
driver . 


Source  Code  Location  - - 
MENUSUBS . FOR 

Programs  Called  -- 

BORDER 

GPL 

GQCF 

GSPLCI 

GSTXCI 

GTX 

WINDOW 


Calling  Programs  -- 
DRIVER 

SUBROUTINE  WINDOW ( WKID ,TRN , PALETT ,XMIN , XMAX ,YMIN , YMAX) : 


51 


This  subroutine  sets  a window  and  a viewport  in  a way  that  preserves  the 
aspect  ratio  of  the  world  coordinates.  (See  the  GKS  manual  for  definitions 
of  graphics  terms.) 

Source  Code  Location  -- 
GKSUTIL. FOR 

Input  Variables  -- 
WKID:  INTEGER*2 

Workstation  identifier 
TRN : INTEGER*2 

Transformation  number  (between  1 and  7) 

PALETT : I NT EGER* 2 

Palette  identifier  (1  or  2) 

XMIN : REAL*4 

Smallest  x value  of  world  coordinates 
XMAX : REAL*4 

Largest  x value  of  world  coordinates 
YMIN : REAL*4 

Smallest  y value  of  world  coordinates 
YMAX : REAL*4 

Largest  y value  of  world  coordinates 

Programs  Called  -- 

GQMDS 

GSELNT 

GSVP 

GSWKVP 

GSWKWN 

GSWN 

SETCOL 

Calling  Programs  -- 

SPLTWN 

TOPMNU 

SUBROUTINE  WRKMAP(IERR, ID, M,XC ENT, YCENT, INDEX, PNT.ZIPCLR, 

ZIP5, WORK, MAXPLT.XPLOT.YPLOT.LONG, PERM)  : 

This  subroutine  initializes  the  display  of  a workload  map.  It  is  executed 
when  the  user  chooses  "F2  - Display  workload"  from  the  top  menu.  It  first 
asks  the  user  to  choose  the  category  of  workload  to  be  displayed  and  then 
sets  a series  of  switches  corresponding  to  the  desired  columns  of  the 
workload  file  WORKLOAD. id.  These  columns  are  read  and  summed  for  each  zip 
code.  Then  the  workloads  are  divided  into  six  equally  spaced  ranges  (or  the 
user  may  specify  other  ranges) . Each  zip  code  is  assigned  a color  according 
to  the  range  its  workload  falls  into.  The  colors  are  passed  in  an  array  to 
the  subroutine  DISPLY  which  draws  the  map. 

Source  Code  Location  -- 
DRIVER. FOR 

Input  Variables  -- 

ID:  CHARACTER*2 
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M: 

XCENT(M) : 
YCENT(M) : 
INDEX(M) : 

PNT(M) : 

ZIP5 (M) : 

MAXPLT : 

Output  Variables 
I ERR: 

ZIPCLR(M) : 
WORK(M) : 

XPLOT ( 2*MAXPLT ) : 

YPLOT ( 2 *MAXPLT ) : 

LONG ( 2*MAXPLT ) : 
PERM ( 2*MAXPLT ) : 

Programs  Called 

DISPLY 

PAUSE 

RANGES 

READBF 

ROUND 

Calling  Programs 
DRIVER 


District  number 
INTEGERS 

Number  of  zip  codes 
REAL*4 

Array  containing  x-coordinates  of  centroids, 
sorted  according  to  increasing  x and  y 
REAL*4 

Array  containing  y-coordinates  of  centroids, 
sorted  according  to  increasing  x and  y 
INTEGERS 

Zip  code  index  array  - - 

INDEX(I)  is  the  original  index  of  the  zip  code 
with  centroid  (XCENT(I) , YCENT(I) ) before  sorting 
INTEGERS 
Pointer  array  -- 

PNT(I)  points  to  the  beginning  of  information  on 
the  zip  code  with  centroid  (XCENT(I) ,YCENT(I) ) in 
the  zip  code  boundary  file 
INTEGERS 

Array  of  five-digit  zip  codes,  in  original 

sequential  order 

INTEGER*4 

Maximum  number  of  plotting  points  allowed  in  a 
map  region 


INTEGERS 

Error  flag  -- 

IERR=0  for  normal  return 

IERR=1  if  an  error  was  encountered 

INTEGERS 

Zip  code  color  array  for  workload 
INTEGER*4 

Work  array  containing  workload  for  each  zip  code 
REAL*4 

Work  array  containing  x coordinates  of  points  to 
plot  in  a map  region 
REAL* 4 

Work  array  containing  y coordinates  of  points  to 

plot  in  a map  region 

REAL*4 

Work  array 

INTEGERS 

Work  array 
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SUBROUTINE  ZIPBND(IERR, ID ,XMIN , YMIN ,XMAX, YMAX.MAXZPS ,NZIPS , 

ZIP5 , PNTR, MAXPTS ,X,Y) : 

This  subroutine  converts  the  GDT  zip  code  boundary  file  (in  URBAN  format)  to 
binary  direct  access  form.  For  zip  codes  which  contain  holes,  it  reorders 
the  interior  points  so  the  connector  segment  will  be  as  short  as  possible. 

It  also  inserts  pointers  in  each  zip  code  header  record  (Type  3 record)  to 
point  to  the  location  of  further  information  on  the  same  zip  code,  if  any. 

Source  Code  Location  -- 
GDTINST1 . FOR 

Input  Variables  -- 

ID:  CHARACTER*2 


XMIN : 

Two-digit  district  identification  number 
REAL*4 

YMIN: 

Minimum  x coordinate  of  state  map 
REAL*4 

XMAX: 

Minimum  y coordinate  of  state  map 
REAL*4 

YMAX: 

Maximum  x coordinate  of  state  map 
REAL*4 

MAXZPS : 

Maximum  y coordinate  of  state  map 
INTEGERS 

MAXPTS : 

Maximum  number  of  zip  codes  allowed 
INTEGERS 

Maximum  number  of  points  allowed  in  a map  region 

Output  Variables  -- 
I ERR:  INTEGERS 


NZIPS : 

Error  flag  -- 

IERR=0  for  normal  return 

IERR=1  if  an  error  was  encountered 

INTEGERS 

ZIP5 (NZIPS ) : 

Number  of  distinct  zip  codes  in  boundary  file 
INTEGERS 

Array  of  five-digit  zip  code  numbers,  in 
sequential  order 

PNTR(NZIPS) : 

INTEGERS 

Pointer  into  boundary  file  -- 

PNTR(I)  is  the  record  number  of  the  beginning  of 
information  on  zip  code  ZIP5(I) 

X(MAXPTS) : 

REAL*4 

Work  array  containing  x coordinates  of  a map  region 

Y (MAXPTS ) : 

REAL*4 

Work  array  containing  y coordinates  of  a map  region 

Programs  Called  -- 
ORDER 

Calling  Programs  -- 
GDTINST1 

SUBROUTINE  ZIPMAP(IERR,TRN,PALETT, ID, MENU, ZOOM, COLOR, XMIN.XMAX, 
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YMIN , YMAX , M , XCENT , YCENT , INDEX , PNT , ZIPCLR , 
MAXPLT , XPLOT , YPLOT , LONG , PERM) : 


This  subroutine  draws  a zip  code  map  either  for  a full  state  or  for  a 
smaller  area.  Centroids  are  included,  and  the  zip  codes  are  colored  if 
specified.  The  zip  code  boundaries  are  read  from  the  file  ZIPCODE.id.  If 
the  whole  state  is  not  to  be  drawn,  but  only  a smaller  region  specified  by  a 
zoom  rectangle,  a search  is  done  first  to  find  the  first  and  last  zip  codes 
(as  given  in  the  sorted  centroid  list)  included  in  the  rectangle. 

Source  Code  Location  -- 
MAPSUBS . FOR 


Input  Variables 
TRN : 

PALETT : 

ID: 

MENU: 

ZOOM: 

COLOR : 


XMIN : 
XMAX: 
YMIN: 
YMAX: 

M: 

XCENT (M) : 
YCENT (M) : 
INDEX(M) : 
PNT(M) : 


I NT EGER* 2 

Transformation  number 
INTEGER*2 

Palette  identifier  (1  or  2) 

CHARACTER*2 
District  number 
INTEGER*2 
Menu  type  switch 
LOGICAL 

Zoom  indicator  -- 

ZOOM=. FALSE,  if  entire  state  is  to  be  drawn 
ZOOM«=.TRUE.  if  only  part  of  state  is  to  be  drawn 
LOGICAL 

Color  indicator  -- 

COLOR=.TRUE.  if  zip  codes  are  to  be  colored  as 
they  are  drawn 

COLOR= . FALSE . if  just  zip  code  boundaries  are  to 
be  drawn 
REAL* 4 

X coordinate  of  lower  left  corner  of  zoom 
rectangle  (used  only  if  ZOOM=.TRUE.) 

REAL*4 

X coordinate  of  upper  right  corner  of  zoom 
rectangle  (used  only  if  ZOOM=.TRUE.) 

REAL*4 

Y coordinate  of  lower  left  corner  of  zoom 
rectangle  (used  only  if  ZOOM=.TRUE.) 

REAL*4 

Y coordinate  of  upper  right  corner  of  zoom 
rectangle  (used  only  if  ZOOM= . TRUE . ) 

INTEGER*4 

Number  of  zip  codes 
REAL*4 

Array  containing  x-coordinates  of  centroids 
REAL* 4 

Array  containing  y- coordinates  of  centroids 
INTEGER*2 

Zip  code  index  array 

INTEGER*2 

Pointer  array  -- 
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ZIPCLR(M) : 


MAXPLT : 


Output  Variables 
I ERR : 


XMIN : 


XMAX: 


YMIN: 


YMAX : 


XPLOT ( 2*MAXPLT) : 


YPLOT ( 2*MAXPLT ) : 


LONG ( 2*MAXPLT ) : 
PERM ( 2*MAXPLT ) : 


Programs  Called 

BEEP 

BORDER 

CLSGKS 

GFA 

GPL 

GPM 

GQCF 

GQTXX 

GSMK 

GSPLCI 

GSPMCI 

GSTXCI 

GTX 


PNT(I)  points  to  the  beginning  of  information  on 
the  zip  code  with  centroid  (XCENT(I) , YCENT(I) ) in 
the  zip  code  boundary  file 
INTEGERS 

Zip  code  color  array  -- 

(Colors  used  only  if  COLOR- . TRUE . ) 

Positive  value:  Centroid  drawn  as  asterisk 
Negative  value:  Centroid  drawn  as  small  box 
INTEGER*4 

Maximum  number  of  plotting  points  allowed  in  a 
map  region 


INTEGER*4 

Error  flag  -- 

IERR-0  for  normal  return 

IERR=1  if  an  error  was  encountered 

REAL*4 

X coordinate  of  lower  left  corner  of  map 
(same  as  input  XMIN  if  ZOOM-. TRUE.) 

REAL*4 

X coordinate  of  upper  right  corner  of  map 
(same  as  input  XMAX  if  ZOOM-. TRUE.) 

REAL* 4 

Y coordinate  of  lower  left  corner  of  map 
(same  as  input  YMIN  if  ZOOM-. TRUE.) 

REAL*4 

Y coordinate  of  upper  right  corner  of  map 
(same  as  input  YMAX  if  ZOOM-. TRUE.) 

REAL*4 

Work  array  containing  x coordinates  of  points  to 
plot  in  a map  region 
REAL* 4 

Work  array  containing  y coordinates  of  points  to 

plot  in  a map  region 

REAL*4 

Work  array 

INTEGER*2 

Work  array 


56 


REVERS 

SPLTWN 

STYLE 

THIN 

Calling  Programs  -- 

DISPLY 

ZOOMIN 

SUBROUTINE  ZOOKIN  ( IERR , TRN , PALETT  f ID , MENU , XMIN , XMAX , YMIN , YMAX , 

M , XCENT , YCENT , INDEX , PNT , ZIPCLR , 

MAXPLT , XPLOT , YPLOT , LONG , PERM)  : 

This  subroutine  allows  the  user  to  draw  a box  on  a previously  drawn  map  and 
then  zooms  in  on  the  boxed  area. 


Source  Code  Location  -- 

MAPSUBS . FOR 

Input  Variables 

TRN: 

INTEGER*2 

Transformation  number 

PALETT : 

INTEGERS 

Palette  identifier  (1 

or  2) 

ID: 

CHARACTER*2 

District  number 

MENU: 

INTEGER*2 

Menu  type  switch 

XMIN: 

REAL* 4 

X coordinate  of  lower 

left  corner  of  current  map 

XMAX: 

REAL*  4 

X coordinate  of  upper 

right  corner  of  current 

map 

YMIN: 

REAL* 4 

Y coordinate  of  lower 

left  corner  of  current  map 

YMAX: 

REAL*4 

Y coordinate  of  upper 

right  corner  of  current 

map 

M: 

INTEGER*4 

Number  of  zip  codes 

XCENT (M) : 

REAL*4 

Array  containing  x-coordinates  of  centroids 

YCENT (M) : 

REAL*  4 

Array  containing  y-coordinates  of  centroids 

INDEX(M) : 

INTEGER*2 

Zip  code  index  array 

PNT (M) : 

INTEGER*2 

Pointer  array  -- 

PNT(I)  points  to  the  beginning  of  information 

on 

the  zip  code  with  centroid  (XCENT ( I ) , YCENT( I ) ) 

in 

the  zip  code  boundary 

file 

ZIPCLR(M) : 

INTEGER*2 

Zip  code  color  array 

MAXPLT: 

INTEGER*4 

Maximum  number  of  plotting  points  allowed  in  a 
map  region 
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Output  Variables  -- 
I ERR:  INTEGERS 

Error  flag  -- 
IERR=0  for  normal  return 
IERR*=1  if  an  error  was  encountered 
IERR=2  if  zoom  was  cancelled  by  user 
TRN : I NT EGER* 2 

Transformation  number 
XMIN : REAL*4 

X coordinate  of  lower  left  corner  of  zoom  region 
XMAX : REAL*4 

X coordinate  of  upper  right  corner  of  zoom  region 
YMIN:  REAL*4 

Y coordinate  of  lower  left  corner  of  zoom  region 

YMAX : REAL*4 

Y coordinate  of  upper  right  corner  of  zoom  region 
XPL0T(2*MAXPLT) : REAL*4 

Work  array  containing  x coordinates  of  points  to 
plot  in  a map  region 
YPLOT ( 2*MAXPLT ) : REAL*4 

Work  array  containing  y coordinates  of  points  to 
plot  in  a map  region 
L0NG(2*MAXPLT) : REAL*4 

Work  array 

PERM( 2*MAXPLT) : INTEGER*2 

Work  array 

Programs  Called  -- 

CRSBOX 

ERSMNU 

GCLRWK 

GINST 

GQCF 

GQNDS 

GRQST 

GSELNT 

GSTXCI 

GTX 

REVERS 

ZIPMAP 

Calling  Programs  -- 
DISPLY 
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Section  V:  Changing  the  Program  to  Correspond  to  Changes  in  the  Workload 
File  Format 


The  current  version  of  the  POD  location  system  (5.0)  assumes  that  the 
workload  file  WORKLOAD. id  contains  three  header  records  followed  by  a 
workload  record  for  each  zip  code.  Each  workload  record  contains  a zip  code 

followed  by  36  items:  14  BMF  Examination  entries,  10  IMF  Examination 

entries,  4 BMF  Collection  entries,  2 IMF  Collection  entries,  and  6 entries 
for  display  purposes  only.  From  year  to  year  this  format  may  change,  and  if 

so,  some  subroutines  in  the  POD  location  system  must  be  revised.  The 

following  routines  may  need  to  be  changed. 

Subroutine  COMP  in  file  GDTINST1.F0R  -- 

Line  293:  DO  200  1=1,3 

Line  294:  READ (2 , *) 

Line  295:  200  CONTINUE 

This  loop  skips  over  the  three  header  records  at  the  beginning  of  the 
workload  file.  It  only  needs  to  be  changed  if  the  number  of  header 
records  changes. 

Function  COSTFN  in  file  DRIVER. FOR  -- 

Line  333:  DO  500  1=25,30 

Line  334:  TDITDA=TDITDA+WRK(I) 

Line  335:  500  CONTINUE 

This  loop  calculates  the  total  Collection  workload  for  a zip  code,  read 
from  columns  25  through  30  of  the  workload  file.  The  loop  should  be 
revised  if  the  Collection  columns  change. 

Subroutine  SOLVE  in  file  DRIVER. FOR  -- 

Line  799:  PARAMETER (NCLASS=30) 

The  parameter  NCLASS  defines  the  number  of  categories  of  workload  in  the 
workload  file,  not  including  display-only  categories. 

Line  977:  READ( 10 , *)TEMP , ( IRSFCT( I ) , 1=1 , NCLASS ) 

Line  978:  READ ( 10 , *)TEMP , (TXPFCT ( I ) , 1=1 , NCLASS ) 

Line  979:  READ (10,*) TEMP, (STFFCT(I) , 1=1 .NCLASS) 

These  lines  read  the  three  header  records  from  the  workload  file  and  only 
need  to  be  changed  if  the  number  of  header  records  changes. 

Subroutine  WRKMAP  in  file  DRIVER. FOR  -- 


Line  1415:  CHARACTER  TITLE*20 , VECTOR*36 

Line  1424:  PARAMETER (NCLASS=3 6) 

The  "36"  in  these  lines  represents  the  total  number  of  workload 
categories  in  the  workload  file,  including  display-only  categories. 


Line  1460 
Line  1461 
Line  1462 


DO  200  1=1,24 
SWITCH ( I )=1 
200  CONTINUE 
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This  loop  turns  on  a switch  for  each  category  of  Examination  workload, 
read  from  columns  1 through  24  of  the  workload  file.  The  loop  should  be 
revised  if  the  Examination  columns  change. 


Line  1465:  DO  202  1=25,30 

Line  1466:  SWITCH(I)=1 

Line  1467:  202  CONTINUE 

This  loop  turns  on  a switch  for  each  category  of  Collection  workload, 
read  from  columns  25  through  30  of  the  workload  file.  The  loop  should  be 
revised  if  the  Collection  columns  change. 


Line  1469: 
Line  1470: 
Line  1471: 
Line  1472: 
Line  1473: 
(Lines  1500- 


PRINT 

PRINT 

PRINT 

PRINT 

PRINT 


' COLUMN  DESCRIPTIONS  ' 

' 1-14  BMF  EXAMINATION  26,28  BMF  TDA  COLLECTION' 
'15-24  IMF  EXAMINATION  29  IMF  TDI  COLLECTION' 
'25,27  BMF  TDI  COLLECTION  30  IMF  TDA  COLLECTION' 
'31-36  OTHER  WORKLOAD  FOR  DISPLAY  PURPOSES  ONLY' 


1504  are  identical.) 


These  lines  should  be  modified  to  correspond  to  any  changes  in  the 
workload  file  format. 


Line  1477:  PRINT  *, 'Enter  number  (from  1 to  36  of  column  to  be  ', 

Line  1478:  + 'displayed:  ' 

Line  1492:  PRINT  *, 'Error  --  please  enter  a number  between  1 and  36.' 

The  "36"  in  these  lines  represents  the  total  number  of  workload 
categories  in  the  workload  file,  including  display-only  categories. 

Line  1509:  PRINT*,'  111111111122222222223333333' 

Line  1510:  PRINT  *,' 123456789012345678901234567890123456 ' 

These  lines  print  column  labels  for  each  category  of  workload,  including 
display-only  columns. 

Line  1564:  DO  600  1=1,3 

Line  1565:  READ(10 ,*) 

Line  1566:  600  CONTINUE 

This  loop  skips  over  the  three  header  records  at  the  beginning  of  the 
workload  file.  It  only  needs  to  be  changed  if  the  number  of  header 
records  changes. 


Subroutine  OPTION  in  file  IOSUBS.FOR  -- 


Line  496: 
Line  497 : 
Line  498: 
This  loop 
workload, 
should  be 


DO  200  1=1,14 
SWITCH(I)=1 
200  CONTINUE 

turns  on  a switch  for  each  category  of  BMF  Examination 
read  from  columns  1 through  14  of  the  workload  file.  The 
revised  if  the  BMF  Examination  columns  change. 


loop 


Line  501: 
Line  502 : 
Line  503: 
This  loop 
workload , 
should  be 


DO  201  1=15,24 
SWITCH(I)=1 
201  CONTINUE 

turns  on  a switch  for  each  category  of  IMF  Examination 

read  from  columns  15  through  24  of  the  workload  file.  The  loop 

revised  if  the  IMF  Examination  columns  change. 
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Line  506:  DO  202  1=25,28 

Line  507:  SWITCH(I)=1 

Line  508:  202  CONTINUE 

This  loop  turns  on  a switch  for  each  category  of  BMF  Collection  workload, 
read  from  columns  25  through  28  of  the  workload  file.  The  loop  should  be 
revised  if  the  BMF  Collection  columns  change. 

Line  511:  DO  203  1=29,30 

Line  512:  SWITCH(I)=1 

Line  513:  203  CONTINUE 

This  loop  turns  on  a switch  for  each  category  of  IMF  Collection  workload, 
read  from  columns  29  and  30  of  the  workload  file.  The  loop  should  be 
revised  if  the  IMF  Collection  columns  change. 

Subroutine  REPPRB  in  file  IOSUBS.FOR  -- 


Lines  1022-1107  contain  labels  for  each  category  of  workload,  to  be 
listed  in  the  report  file.  These  labels  should  be  updated  each  year. 

Subroutine  REPSOL  in  file  IOSUBS.FOR  -- 


Line  1160:  PARAMETER (NCLASS=30) 

The  parameter  NCLASS  defines  the  number  of  categories  of  workload  in  the 
workload  file,  not  including  display-only  categories. 


Line  1329 
Line  1330 
Line  1331 
Line  1332 


DO  600  1=1,2 
READ(10 ,*) 

600  CONTINUE 

READ (10,*) TEMP, (STFFAC( I) ,1=1, NCLASS) 


These  lines  skip  over  the  first  two  header  records  at  the  beginning  of 
the  workload  file  and  then  read  the  staffing  factors  from  the  third  line. 
These  lines  only  need  to  be  changed  if  the  organization  of  the  header 
information  changes. 


Line  1347 
Line  1348 
Line  1349 
Line  1350 
Line  1351 
Line  1352 
This  loop 
read 

revised  if  the  IMF  Examination  columns  change 


DO  700  1=15,24 

Z1=STFFAC ( I ) *WRK ( I ) 

IMFEXM(ZIPCLR(POD) )=IMFEXM(ZIPCLR(POD) )+Zl 
IMFEX2 (ZIPCLR(POD) )=IMFEX2 (ZIPCLR(POD) )+WRK(I) 
T0TEXM=T0TEXM+Z1 
700  CONTINUE 

calculates  staffing  information  for  IMF  Examination  workload, 


from  columns  15  through  24  of  the  workload  file.  The  loop  should  be 


Line  1354 
Line  1355 
Line  1356 
Line  1357 
Line  1358 
Line  1359 


DO  701  1=1,14 

Z1=STFFAC ( I )*WRK( I ) 

BMFEXM ( ZI PCLR ( POD ) ) =BMFEXM ( ZI PCLR ( POD ) ) +Z 1 
BMFEX2 ( ZI PCLR ( POD ) ) -BMFEX2 ( ZI PCLR ( POD ) ) +WRK ( I ) 
T0TEXM=T0TEXM+Z1 
701  CONTINUE 


This  loop  calculates  staffing  information  for  BMF  Examination  workload, 
read  from  columns  1 through  14  of  the  workload  file.  The  loop  should  be 
revised  if  the  BMF  Examination  columns  change. 
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Line  1361:  Z1=STFFAC(29)*WRK(29) 

Line  1362:  TDICOL(ZIPCLR(POD)  )-=TDICOL(ZIPCLR(POD)  )+Zl 

Line  1363:  TDIC02 (ZIPCLR(POD) )=TDIC02 (ZIPCLR(POD) )+WRK(29) 

These  lines  calculate  staffing  information  for  IMF  TDI  Collection 
workload,  read  from  column  29  of  the  workload  file.  These  lines  should 
be  changed  if  the  IMF  TDI  Collection  column  changes. 

Line  1366:  Z1-STFFAC(25)*WRK(25)+STFFAC(27)*WRK(27) 

Line  1367:  TDICOL(ZIPCLR(POD) )-TDICOL(ZIPCLR(POD) )+Zl 

Line  1368:  TDIC02 (ZIPCLR(POD) )-TDIC02 (ZIPCLR(POD) )+WRK(25)+WRK(27) 

These  lines  calculate  staffing  information  for  BMF  TDI  Collection 
workload,  read  from  columns  25  and  27  of  the  workload  file.  These  lines 
should  be  changed  if  the  BMF  TDI  Collection  columns  change. 

Line  1371:  Z1=STFFAC(30)*WRK(30) 

Line  1372:  TDACOL(ZIPCLR(POD) )=TDACOL(ZIPCLR(POD) )+Zl 

Line  1373:  TDAC02 (ZIPCLR(POD) )-TDAC02 (ZIPCLR(POD) )+WRK(30) 

These  lines  calculate  staffing  information  for  IMF  TDA  Collection 
workload,  read  from  column  30  of  the  workload  file.  These  lines  should 
be  changed  if  the  IMF  TDA  Collection  column  changes. 

Line  1376:  Z1=STFFAC(26)*WRK(26)+STFFAC(28)*WRK(28) 

Line  1377:  TDACOL(ZIPCLR(POD) )=TDACOL(ZIPCLR(POD) )+Zl 

Line  1378:  TDAC02  (ZIPCLR(POD)  )*=TDAC02  (ZIPCLR(POD)  )+WRK(26)+WRK(28) 

These  lines  calculate  staffing  information  for  BMF  TDA  Collection 
workload,  read  from  columns  26  and  28  of  the  workload  file.  These  lines 
should  be  changed  if  the  BMF  TDA  Collection  columns  change. 

Subroutine  ZIPMAP  in  file  MAPSUBS.FOR  -- 

Line  1090:  CHARACTER  TITLE*20 , VECTOR*36 

The  "36"  in  this  line  represents  the  total  number  of  workload  categories 
in  the  workload  file,  including  display-only  categories. 
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